positiva-consultas-python-sdk 1.0.0__tar.gz

positiva_consultas_python_sdk-1.0.0/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 Seu Nome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...

positiva_consultas_python_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: positiva-consultas-python-sdk
+Version: 1.0.0
+Summary: Client HTTP de comunicacao com a API da Positiva Consultas (PositivaConnect)
+Author-email: Filipe Coelho <filipe@fmconsult.com.br>
+License: MIT License
+        
+        Copyright (c) 2026 Seu Nome
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy...
+        
+Project-URL: Homepage, https://github.com/FMConsult/positiva-consultas-python-sdk
+Project-URL: Bug Tracker, https://github.com/FMConsult/positiva-consultas-python-sdk/issues
+Project-URL: Documentation, https://positivaconnect.positivaconsultas.com.br/developers/documentation
+Keywords: sdk,api,positiva,consultas,juridico360
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# positiva-consultas-python-sdk
+
+Client HTTP Python para a [API Positiva Consultas (PositivaConnect)](https://positivaconnect.positivaconsultas.com.br/developers/documentation).
+
+Escopo inicial:
+
+- Autenticacao OAuth 2.0 Client Credentials (`POST /client/token`)
+- Positiva Juridico 360 (`POST /api/client/provider/juridico360` e `/pdf`)
+
+## Instalacao
+
+```bash
+pip install positiva-consultas-python-sdk
+```
+
+Requer Python >= 3.11 e o ecossistema `fmconsult` (`ApiBase`).
+
+## Credenciais
+
+Configure as variaveis de ambiente:
+
+```bash
+export positiva.consultas.api.client_id="seu_client_id"
+export positiva.consultas.api.client_secret="seu_client_secret"
+```
+
+## Uso
+
+```python
+from positiva.consultas import Juridico360Api, Juridico360ProductCode
+from positiva.consultas.dtos.juridico360 import Juridico360Request
+
+api = Juridico360Api()  # autentica automaticamente via /client/token
+
+# Consulta processual (um ou mais produtos)
+response = api.consultar(
+  Juridico360Request(
+    document="11111111111",
+    product_code=[
+      Juridico360ProductCode.CRIMINAL,
+      Juridico360ProductCode.CIVIL,
+    ],
+  )
+)
+
+print(response.success, response.query_date)
+criminal = response.results.get("CRIMINAL")
+if criminal and criminal.success and criminal.data:
+  print(criminal.data.nome, len(criminal.data.processos or []))
+
+# PDF do relatorio (Base64)
+pdf = api.gerar_pdf(
+  document="11111111111",
+  product_code=["CRIMINAL", "CIVIL"],
+)
+print(pdf.mime_type, len(pdf.pdf_base64 or ""))
+```
+
+### Autenticacao utilitaria
+
+```python
+from positiva.consultas import PositivaConsultasApi
+
+api = PositivaConsultasApi()
+me = api.me()
+print(me.client.name, me.client.cnpj)
+
+api.refresh()   # renova o Bearer
+api.logout()    # invalida o token atual
+```
+
+## Produtos Juridico 360
+
+| Codigo | Descricao |
+| ------ | --------- |
+| `CRIMINAL` | Processos criminais |
+| `CIVIL` | Processos civis |
+| `TRABALHISTA` | Processos trabalhistas |
+| `MP` | Registros do Ministerio Publico |
+| `BNMP` | Banco Nacional de Mandados de Prisao |
+| `EMPREGADOR_IRREGULAR` | Empregadores irregulares |
+
+Homologacao (credencial em ambiente `homolog`): use documentos de teste `11111111111` … `55555555555` — a API devolve dados ficticios determinísticos.
+
+## Documentacao oficial
+
+- [Visao geral](https://positivaconnect.positivaconsultas.com.br/developers/documentation)
+- [Authentication](https://positivaconnect.positivaconsultas.com.br/developers/docs/authentication)
+- [Juridico 360](https://positivaconnect.positivaconsultas.com.br/developers/docs/providers/juridico360)

positiva_consultas_python_sdk-1.0.0/README.md

@@ -0,0 +1,89 @@
+# positiva-consultas-python-sdk
+
+Client HTTP Python para a [API Positiva Consultas (PositivaConnect)](https://positivaconnect.positivaconsultas.com.br/developers/documentation).
+
+Escopo inicial:
+
+- Autenticacao OAuth 2.0 Client Credentials (`POST /client/token`)
+- Positiva Juridico 360 (`POST /api/client/provider/juridico360` e `/pdf`)
+
+## Instalacao
+
+```bash
+pip install positiva-consultas-python-sdk
+```
+
+Requer Python >= 3.11 e o ecossistema `fmconsult` (`ApiBase`).
+
+## Credenciais
+
+Configure as variaveis de ambiente:
+
+```bash
+export positiva.consultas.api.client_id="seu_client_id"
+export positiva.consultas.api.client_secret="seu_client_secret"
+```
+
+## Uso
+
+```python
+from positiva.consultas import Juridico360Api, Juridico360ProductCode
+from positiva.consultas.dtos.juridico360 import Juridico360Request
+
+api = Juridico360Api()  # autentica automaticamente via /client/token
+
+# Consulta processual (um ou mais produtos)
+response = api.consultar(
+  Juridico360Request(
+    document="11111111111",
+    product_code=[
+      Juridico360ProductCode.CRIMINAL,
+      Juridico360ProductCode.CIVIL,
+    ],
+  )
+)
+
+print(response.success, response.query_date)
+criminal = response.results.get("CRIMINAL")
+if criminal and criminal.success and criminal.data:
+  print(criminal.data.nome, len(criminal.data.processos or []))
+
+# PDF do relatorio (Base64)
+pdf = api.gerar_pdf(
+  document="11111111111",
+  product_code=["CRIMINAL", "CIVIL"],
+)
+print(pdf.mime_type, len(pdf.pdf_base64 or ""))
+```
+
+### Autenticacao utilitaria
+
+```python
+from positiva.consultas import PositivaConsultasApi
+
+api = PositivaConsultasApi()
+me = api.me()
+print(me.client.name, me.client.cnpj)
+
+api.refresh()   # renova o Bearer
+api.logout()    # invalida o token atual
+```
+
+## Produtos Juridico 360
+
+| Codigo | Descricao |
+| ------ | --------- |
+| `CRIMINAL` | Processos criminais |
+| `CIVIL` | Processos civis |
+| `TRABALHISTA` | Processos trabalhistas |
+| `MP` | Registros do Ministerio Publico |
+| `BNMP` | Banco Nacional de Mandados de Prisao |
+| `EMPREGADOR_IRREGULAR` | Empregadores irregulares |
+
+Homologacao (credencial em ambiente `homolog`): use documentos de teste `11111111111` … `55555555555` — a API devolve dados ficticios determinísticos.
+
+## Documentacao oficial
+
+- [Visao geral](https://positivaconnect.positivaconsultas.com.br/developers/documentation)
+- [Authentication](https://positivaconnect.positivaconsultas.com.br/developers/docs/authentication)
+- [Juridico 360](https://positivaconnect.positivaconsultas.com.br/developers/docs/providers/juridico360)

positiva_consultas_python_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "positiva-consultas-python-sdk"
+version = "1.0.0"
+description = "Client HTTP de comunicacao com a API da Positiva Consultas (PositivaConnect)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {file = "LICENSE"}
+authors = [
+  {name = "Filipe Coelho", email = "filipe@fmconsult.com.br"},
+]
+keywords = ["sdk", "api", "positiva", "consultas", "juridico360"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest"]
+
+[project.urls]
+"Homepage" = "https://github.com/FMConsult/positiva-consultas-python-sdk"
+"Bug Tracker" = "https://github.com/FMConsult/positiva-consultas-python-sdk/issues"
+"Documentation" = "https://positivaconnect.positivaconsultas.com.br/developers/documentation"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = true

positiva_consultas_python_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

positiva_consultas_python_sdk-1.0.0/src/positiva/consultas/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""SDK Python para a API Positiva Consultas (PositivaConnect)."""
+from positiva.consultas.api import PositivaConsultasApi
+from positiva.consultas.apis.juridico360 import Juridico360Api
+from positiva.consultas.dtos.enums import Juridico360ProductCode, MpKind
+
+__all__ = [
+  'PositivaConsultasApi',
+  'Juridico360Api',
+  'Juridico360ProductCode',
+  'MpKind',
+]

positiva_consultas_python_sdk-1.0.0/src/positiva/consultas/api.py

@@ -0,0 +1,106 @@
+# -*- coding: utf-8 -*-
+"""Cliente base Positiva Consultas — autenticacao OAuth 2.0 Client Credentials."""
+from __future__ import annotations
+
+import base64
+import logging
+import os
+
+import jsonpickle
+from fmconsult.http.api import ApiBase
+from fmconsult.utils.url import UrlUtil
+from http import HTTPMethod
+
+from positiva.consultas.dtos.auth import (
+  ClientMeResponse,
+  LogoutResponse,
+  TokenResponse,
+)
+
+
+class PositivaConsultasApi(ApiBase):
+  """API base com login automatico via ``POST /client/token`` (Basic Auth).
+
+  Variaveis de ambiente:
+  - ``positiva.consultas.api.client_id``
+  - ``positiva.consultas.api.client_secret``
+  """
+
+  API_BASE_URL = 'https://positivaconnect.positivaconsultas.com.br/api'
+
+  def __init__(self):
+    self.api_client_id = os.environ['positiva.consultas.api.client_id']
+    self.api_client_secret = os.environ['positiva.consultas.api.client_secret']
+    self.base_url = self.API_BASE_URL
+    self.access_token: str | None = None
+    self.token_expires_in: int | None = None
+    self.headers: dict[str, str] = {
+      'Accept': 'application/json',
+    }
+    self.__login()
+
+  def __basic_auth_header(self) -> str:
+    raw = f'{self.api_client_id}:{self.api_client_secret}'.encode()
+    return f'Basic {base64.b64encode(raw).decode()}'
+
+  def __apply_bearer(self, access_token: str, expires_in: int | None = None) -> None:
+    self.access_token = access_token
+    self.token_expires_in = expires_in
+    self.headers['Authorization'] = f'Bearer {access_token}'
+
+  def __login(self) -> TokenResponse:
+    """POST /client/token — Authorization Basic (client_id:client_secret)."""
+    logging.info('authenticating via Positiva Consultas /client/token...')
+    self.headers = {
+      'Accept': 'application/json',
+      'Authorization': self.__basic_auth_header(),
+    }
+    url = UrlUtil().make_url(self.base_url, ['client', 'token'])
+    res = self.call_request(http_method=HTTPMethod.POST, request_url=url)
+    data = jsonpickle.decode(res)
+    token = TokenResponse.from_dict(data)
+    if token is None or not token.access_token:
+      raise Exception(
+        data.get('error_description')
+        or data.get('message')
+        or 'Falha ao obter access_token'
+      )
+    self.__apply_bearer(token.access_token, token.expires_in)
+    return token
+
+  def me(self) -> ClientMeResponse:
+    """GET /client/me — dados do cliente autenticado."""
+    logging.info('fetching Positiva Consultas /client/me...')
+    url = UrlUtil().make_url(self.base_url, ['client', 'me'])
+    res = self.call_request(http_method=HTTPMethod.GET, request_url=url)
+    parsed = ClientMeResponse.from_dict(jsonpickle.decode(res))
+    if parsed is None or parsed.client is None:
+      raise Exception('Resposta inesperada de /client/me')
+    return parsed
+
+  def refresh(self) -> TokenResponse:
+    """POST /client/refresh — renova o Bearer atual."""
+    logging.info('refreshing Positiva Consultas token...')
+    url = UrlUtil().make_url(self.base_url, ['client', 'refresh'])
+    res = self.call_request(http_method=HTTPMethod.POST, request_url=url)
+    data = jsonpickle.decode(res)
+    token = TokenResponse.from_dict(data)
+    if token is None or not token.access_token:
+      raise Exception(
+        data.get('error_description')
+        or data.get('message')
+        or 'Falha ao renovar access_token'
+      )
+    self.__apply_bearer(token.access_token, token.expires_in)
+    return token
+
+  def logout(self) -> LogoutResponse:
+    """POST /client/logout — invalida o token atual."""
+    logging.info('logging out Positiva Consultas token...')
+    url = UrlUtil().make_url(self.base_url, ['client', 'logout'])
+    res = self.call_request(http_method=HTTPMethod.POST, request_url=url)
+    parsed = LogoutResponse.from_dict(jsonpickle.decode(res))
+    self.access_token = None
+    self.token_expires_in = None
+    self.headers.pop('Authorization', None)
+    return parsed or LogoutResponse()

positiva_consultas_python_sdk-1.0.0/src/positiva/consultas/apis/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+from positiva.consultas.apis.juridico360 import Juridico360Api
+
+__all__ = ['Juridico360Api']

positiva_consultas_python_sdk-1.0.0/src/positiva/consultas/apis/juridico360.py

@@ -0,0 +1,169 @@
+# -*- coding: utf-8 -*-
+"""Cliente HTTP Positiva Juridico 360."""
+from __future__ import annotations
+
+import logging
+from typing import Sequence
+
+import jsonpickle
+from fmconsult.utils.url import UrlUtil
+from http import HTTPMethod
+
+from positiva.consultas.api import PositivaConsultasApi
+from positiva.consultas.dtos.enums import Juridico360ProductCode
+from positiva.consultas.dtos.juridico360 import (
+  Juridico360Options,
+  Juridico360PdfResponse,
+  Juridico360Request,
+  Juridico360Response,
+)
+from positiva.consultas.dtos.serde import digits_only, to_wire
+
+_VALID_PRODUCTS = {p.value for p in Juridico360ProductCode}
+
+
+def _normalize_product_codes(
+  product_code: Sequence[str | Juridico360ProductCode],
+) -> list[str]:
+  if not product_code:
+    raise ValueError('product_code é obrigatório e não pode ser vazio')
+  normalized: list[str] = []
+  for code in product_code:
+    value = str(to_wire(code))
+    if value not in _VALID_PRODUCTS:
+      raise ValueError(
+        f'product_code inválido: {value!r}. '
+        f'Valores aceitos: {sorted(_VALID_PRODUCTS)}'
+      )
+    if value not in normalized:
+      normalized.append(value)
+  return normalized
+
+
+def _require_document(document: str | None) -> str:
+  digits = digits_only(document)
+  if len(digits) not in (11, 14):
+    raise ValueError(
+      'document deve ser CPF (11 dígitos) ou CNPJ (14 dígitos)'
+    )
+  return digits
+
+
+def _coerce_request(
+  request: Juridico360Request | dict,
+) -> Juridico360Request:
+  if isinstance(request, Juridico360Request):
+    return request
+  parsed = Juridico360Request.from_dict(request)
+  if parsed is None:
+    raise ValueError('request inválido')
+  return parsed
+
+
+class Juridico360Api(PositivaConsultasApi):
+  """Consulta processual Positiva Juridico 360."""
+
+  def consultar(
+    self, request: Juridico360Request | dict
+  ) -> Juridico360Response:
+    """POST /api/client/provider/juridico360."""
+    logging.info('consulting Positiva Juridico 360...')
+    req = _coerce_request(request)
+    payload = {
+      'document': _require_document(req.document),
+      'product_code': _normalize_product_codes(req.product_code),
+    }
+    if req.options is not None:
+      options = req.options.to_dict() if isinstance(req.options, Juridico360Options) else dict(req.options)
+      if options:
+        if options.get('page_size') is not None and int(options['page_size']) > 100:
+          raise ValueError('options.page_size máximo é 100')
+        payload['options'] = options
+
+    url = UrlUtil().make_url(
+      self.base_url, ['client', 'provider', 'juridico360']
+    )
+    res = self.call_request(
+      http_method=HTTPMethod.POST,
+      request_url=url,
+      payload=payload,
+    )
+    parsed = Juridico360Response.from_dict(jsonpickle.decode(res))
+    if parsed is None:
+      raise Exception('Resposta inesperada de Juridico 360')
+    return parsed
+
+  def consultar_por_documento(
+    self,
+    document: str,
+    product_code: Sequence[str | Juridico360ProductCode],
+    *,
+    options: Juridico360Options | dict | None = None,
+  ) -> Juridico360Response:
+    """Atalho tipado para ``consultar``."""
+    opts = None
+    if isinstance(options, Juridico360Options):
+      opts = options
+    elif isinstance(options, dict):
+      opts = Juridico360Options.from_dict(options)
+    return self.consultar(
+      Juridico360Request(
+        document=document,
+        product_code=list(product_code),
+        options=opts,
+      )
+    )
+
+  def gerar_pdf(
+    self,
+    request: Juridico360Request | dict | None = None,
+    *,
+    document: str | None = None,
+    product_code: Sequence[str | Juridico360ProductCode] | None = None,
+    options: Juridico360Options | dict | None = None,
+  ) -> Juridico360PdfResponse:
+    """POST /api/client/provider/juridico360/pdf — retorna PDF em Base64."""
+    logging.info('generating Positiva Juridico 360 PDF...')
+    if request is not None:
+      req = _coerce_request(request)
+    else:
+      if document is None or product_code is None:
+        raise ValueError(
+          'informe request ou (document + product_code) para gerar PDF'
+        )
+      opts = None
+      if isinstance(options, Juridico360Options):
+        opts = options
+      elif isinstance(options, dict):
+        opts = Juridico360Options.from_dict(options)
+      req = Juridico360Request(
+        document=document,
+        product_code=list(product_code),
+        options=opts,
+      )
+
+    payload = {
+      'document': _require_document(req.document),
+      'product_code': _normalize_product_codes(req.product_code),
+    }
+    if req.options is not None:
+      options_dict = (
+        req.options.to_dict()
+        if isinstance(req.options, Juridico360Options)
+        else dict(req.options)
+      )
+      if options_dict:
+        payload['options'] = options_dict
+
+    url = UrlUtil().make_url(
+      self.base_url, ['client', 'provider', 'juridico360', 'pdf']
+    )
+    res = self.call_request(
+      http_method=HTTPMethod.POST,
+      request_url=url,
+      payload=payload,
+    )
+    parsed = Juridico360PdfResponse.from_dict(jsonpickle.decode(res))
+    if parsed is None:
+      raise Exception('Resposta inesperada de Juridico 360 PDF')
+    return parsed

positiva_consultas_python_sdk-1.0.0/src/positiva/consultas/dtos/__init__.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+from positiva.consultas.dtos.auth import (
+  AvailableProduct,
+  ClientInfo,
+  ClientMeResponse,
+  LogoutResponse,
+  ProductFeature,
+  ProviderProduct,
+  TokenResponse,
+)
+from positiva.consultas.dtos.enums import DocumentType, Juridico360ProductCode, MpKind
+from positiva.consultas.dtos.juridico360 import (
+  Juridico360Options,
+  Juridico360PdfResponse,
+  Juridico360ProductData,
+  Juridico360ProductResult,
+  Juridico360Request,
+  Juridico360Response,
+  PenaPrevista,
+)
+
+__all__ = [
+  'AvailableProduct',
+  'ClientInfo',
+  'ClientMeResponse',
+  'DocumentType',
+  'Juridico360Options',
+  'Juridico360PdfResponse',
+  'Juridico360ProductCode',
+  'Juridico360ProductData',
+  'Juridico360ProductResult',
+  'Juridico360Request',
+  'Juridico360Response',
+  'LogoutResponse',
+  'MpKind',
+  'PenaPrevista',
+  'ProductFeature',
+  'ProviderProduct',
+  'TokenResponse',
+]