sharpfy-nextapi 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. sharpfy_nextapi-0.2.0/LICENSE +21 -0
  2. sharpfy_nextapi-0.2.0/PKG-INFO +283 -0
  3. sharpfy_nextapi-0.2.0/README.md +256 -0
  4. sharpfy_nextapi-0.2.0/pyproject.toml +52 -0
  5. sharpfy_nextapi-0.2.0/setup.cfg +4 -0
  6. sharpfy_nextapi-0.2.0/sharpfy_nextapi/__init__.py +15 -0
  7. sharpfy_nextapi-0.2.0/sharpfy_nextapi/_transport.py +40 -0
  8. sharpfy_nextapi-0.2.0/sharpfy_nextapi/_validation.py +94 -0
  9. sharpfy_nextapi-0.2.0/sharpfy_nextapi/_version.py +1 -0
  10. sharpfy_nextapi-0.2.0/sharpfy_nextapi/client.py +170 -0
  11. sharpfy_nextapi-0.2.0/sharpfy_nextapi/errors.py +103 -0
  12. sharpfy_nextapi-0.2.0/sharpfy_nextapi/models.py +469 -0
  13. sharpfy_nextapi-0.2.0/sharpfy_nextapi/py.typed +1 -0
  14. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/__init__.py +0 -0
  15. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/base.py +15 -0
  16. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/ceps.py +36 -0
  17. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/cnpj.py +47 -0
  18. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/creditos.py +8 -0
  19. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/empresas.py +21 -0
  20. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/localidades.py +26 -0
  21. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/mercado.py +24 -0
  22. sharpfy_nextapi-0.2.0/sharpfy_nextapi/resources/socios.py +14 -0
  23. sharpfy_nextapi-0.2.0/sharpfy_nextapi.egg-info/PKG-INFO +283 -0
  24. sharpfy_nextapi-0.2.0/sharpfy_nextapi.egg-info/SOURCES.txt +25 -0
  25. sharpfy_nextapi-0.2.0/sharpfy_nextapi.egg-info/dependency_links.txt +1 -0
  26. sharpfy_nextapi-0.2.0/sharpfy_nextapi.egg-info/top_level.txt +1 -0
  27. sharpfy_nextapi-0.2.0/tests/test_contract.py +247 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sharpfy
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,283 @@
1
+ Metadata-Version: 2.4
2
+ Name: sharpfy-nextapi
3
+ Version: 0.2.0
4
+ Summary: SDK oficial da NextAPI para Python: CNPJ (inclusive alfanumérico), Simples Nacional, CEP, sócios e mercado. Sem dependências.
5
+ Author-email: Sharpfy <contato@sharpfy.com.br>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://nextapi.com.br
8
+ Project-URL: Documentation, https://github.com/sharpfytecnologia/nextapi-sdk-python#readme
9
+ Project-URL: Repository, https://github.com/sharpfytecnologia/nextapi-sdk-python
10
+ Project-URL: Issues, https://github.com/sharpfytecnologia/nextapi-sdk-python/issues
11
+ Keywords: nextapi,sharpfy,cnpj,receita-federal,simples-nacional,socios,compliance,consulta-cnpj
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.11
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Dynamic: license-file
27
+
28
+ # NextAPI para Python (`sharpfy-nextapi`)
29
+
30
+ SDK oficial da [NextAPI](https://nextapi.com.br) para Python 3.11+: CNPJ (inclusive alfanumérico), Simples Nacional, inscrições estaduais, conformidade, sócios, CEP com busca geográfica, pesquisa de empresas, localidades, mercado e créditos. Sem dependências: só a biblioteca padrão. As respostas são `dict` com tipos (`TypedDict`), prontas para `json.dumps` ou para o seu modelo.
31
+
32
+ ## Requisitos
33
+
34
+ - Python 3.11 ou mais recente (testado no 3.11 e no 3.15)
35
+ - Uma chave de API (veja abaixo)
36
+
37
+ ## Instalação
38
+
39
+ ```bash
40
+ pip install sharpfy-nextapi
41
+ ```
42
+
43
+ ## Chave de API
44
+
45
+ Crie a sua em [app.nextapi.com.br](https://app.nextapi.com.br). São dois tipos:
46
+
47
+ | Prefixo | Ambiente | Custo |
48
+ |---|---|---|
49
+ | `nxa_test_…` | Sandbox: dados de um subconjunto real, limites próprios e CNPJs de teste que provocam cada erro | Nenhum: nada é debitado |
50
+ | `nxa_live_…` | Produção | Créditos do seu plano |
51
+
52
+ O ambiente sai do prefixo da chave; o endereço da API é o mesmo. Guarde a chave na variável de ambiente
53
+ `NEXTAPI_KEY`, que o cliente lê quando você não passa a chave. **Nunca** a coloque no código, no repositório ou num
54
+ front-end: quem tem a chave consome os seus créditos.
55
+
56
+ ## Início rápido
57
+
58
+ ```python
59
+ from sharpfy_nextapi import NextApiClient
60
+
61
+ nextapi = NextApiClient() # lê NEXTAPI_KEY
62
+
63
+ empresa = nextapi.cnpj.consultar("11.222.333/0001-81")
64
+ print(empresa["razaoSocial"], empresa["situacaoCadastral"])
65
+ ```
66
+
67
+ ## Configuração
68
+
69
+ ```python
70
+ import os
71
+ from sharpfy_nextapi import NextApiClient
72
+
73
+ nextapi = NextApiClient(
74
+ os.environ["NEXTAPI_KEY"], # padrão: NEXTAPI_KEY
75
+ base_url="https://api.nextapi.com.br", # só https (http apenas para localhost)
76
+ timeout=15.0, # segundos, por tentativa; padrão 30
77
+ max_retries=3, # padrão 2; 0 desliga
78
+ app_info="minha-app/1.4.0", # identifica a sua aplicação
79
+ )
80
+ ```
81
+
82
+ | Parâmetro | Padrão | Efeito |
83
+ |---|---|---|
84
+ | `api_key` | `NEXTAPI_KEY` | Chave de API; o prefixo define o ambiente (`nextapi.environment`) |
85
+ | `base_url` | `https://api.nextapi.com.br` | Endereço da API |
86
+ | `timeout` | 30.0 | Tempo limite de cada tentativa, em segundos |
87
+ | `max_retries` | 2 | Novas tentativas em falha transitória, só em GET |
88
+ | `app_info` | — | Nome e versão da sua aplicação, nos cabeçalhos |
89
+ | `transport` | `urllib` | Transporte HTTP próprio (proxy, testes) |
90
+
91
+ ### Django, Flask, FastAPI
92
+
93
+ Crie o cliente uma vez, no carregamento do módulo:
94
+
95
+ <!-- readme-check: ignorar (depende do framework) -->
96
+ ```python
97
+ # servicos/nextapi.py
98
+ from sharpfy_nextapi import NextApiClient
99
+ nextapi = NextApiClient(app_info="erp/5.2")
100
+
101
+ # views.py
102
+ from servicos.nextapi import nextapi
103
+ def fornecedor(request, cnpj):
104
+ return JsonResponse(nextapi.cnpj.consultar(cnpj))
105
+ ```
106
+
107
+ O cliente é síncrono. Em código `async` (FastAPI, aiohttp), chame-o numa thread:
108
+ `await asyncio.to_thread(nextapi.cnpj.consultar, cnpj)`.
109
+
110
+ ## Exemplos
111
+
112
+ ### CNPJ
113
+
114
+ ```python
115
+ # Cadastro (1 crédito). tolerance_days: idade máxima aceita do dado em cache (0 a 45); 0 força tempo real.
116
+ empresa = nextapi.cnpj.consultar("11222333000181", tolerance_days=30)
117
+ ao_vivo = nextapi.cnpj.consultar_ao_vivo("11222333000181") # tempo real; exige plano que permita
118
+
119
+ simples = nextapi.cnpj.obter_simples("11222333000181")
120
+ ies = nextapi.cnpj.obter_inscricoes_estaduais("11222333000181")
121
+ conformidade = nextapi.cnpj.obter_conformidade("11222333000181") # sanções e dívida ativa
122
+ alfanumerico = nextapi.cnpj.consultar("12.ABC.345/01DE-35")
123
+ ```
124
+
125
+ ### Lotes (até 100 CNPJs)
126
+
127
+ ```python
128
+ lote = nextapi.cnpj.consultar_lote(["11222333000181", "45997418000153"]) # 1 crédito por CNPJ encontrado
129
+ simples_lote = nextapi.cnpj.obter_simples_lote(["11222333000181"])
130
+
131
+ # Mais de 100: divida em blocos. Lote nunca é repetido sozinho; decida você numa falha.
132
+ for i in range(0, len(todos), 100):
133
+ resultados.extend(nextapi.cnpj.consultar_lote(todos[i:i + 100]))
134
+ ```
135
+
136
+ ### Sócios e grupo econômico
137
+
138
+ ```python
139
+ rel = nextapi.cnpj.obter_relacionamentos("11222333000181", page=1, page_size=50)
140
+ for socio in rel.get("socios") or []:
141
+ # hashSocio só é estável quando vinculoVerificavel é True: não guarde os provisórios.
142
+ empresas = nextapi.socios.listar_empresas(socio["hashSocio"])
143
+ ```
144
+
145
+ ### CEP
146
+
147
+ ```python
148
+ cep = nextapi.ceps.consultar("01001-000")
149
+ por_rua = nextapi.ceps.buscar(uf="SP", nome_municipio="São Paulo", logradouro="Paulista")
150
+ raio = nextapi.ceps.buscar_proximos(latitude=-23.5505, longitude=-46.6333, raio_metro=500)
151
+ vizinhos = nextapi.ceps.buscar_proximos_do_cep("01001000", raio_metro=1000, page_size=100)
152
+ ```
153
+
154
+ ### Pesquisa de empresas, com paginação
155
+
156
+ ```python
157
+ from datetime import date
158
+
159
+ page = 1
160
+ while True:
161
+ pagina = nextapi.empresas.pesquisar(
162
+ uf="SP",
163
+ cnaes="1091101", # vários: separados por vírgula
164
+ data_abertura_inicio=date(2024, 1, 1),
165
+ page=page,
166
+ page_size=100,
167
+ )
168
+ for e in pagina["items"]:
169
+ print(e["cnpj"], e["razaoSocial"])
170
+ if page * pagina["pageSize"] >= pagina["total"]:
171
+ break
172
+ page += 1
173
+ ```
174
+
175
+ ### Localidades, mercado e créditos
176
+
177
+ ```python
178
+ estados = nextapi.estados.listar()
179
+ municipios = nextapi.municipios.listar(uf="MG", page_size=100)
180
+ bh = nextapi.municipios.obter_por_id(3106200)
181
+ cnaes = nextapi.cnaes.listar(page=1, page_size=50)
182
+
183
+ mercado = nextapi.mercado.obter_cnae("1091101", uf="SP", meses=12)
184
+ creditos = nextapi.creditos.consultar()
185
+ print(f"restam {creditos['totalRemainingCredits']} créditos")
186
+ ```
187
+
188
+ ## Erros
189
+
190
+ Toda falha vira uma exceção do SDK; a classe diz o que fazer, e o código detalha.
191
+
192
+ | Classe | Quando | Status / código | O que fazer |
193
+ |---|---|---|---|
194
+ | `NextApiAuthenticationError` | Chave ausente, inválida ou revogada | 401 / 1002, 400 / 1001 | Confira a chave e o ambiente |
195
+ | `NextApiInsufficientCreditsError` | Créditos do período acabaram | 405 / 1004, 1006 | Aguarde a renovação ou compre créditos avulsos |
196
+ | `NextApiPaidPlanRequiredError` | Recurso exige plano pago | 405 / 1012, 1005 | Mude de plano |
197
+ | `NextApiNotFoundError` | CNPJ, CEP ou município não existe | 404 / 1000 | Trate como resultado, não como falha |
198
+ | `NextApiValidationError` | Entrada recusada pela API ou pelo SDK | 400 / 1007, ou status 0 | Corrija a entrada; não repita |
199
+ | `NextApiRateLimitError` | Limite de requisições por minuto | 429 / 1003 | Já repetido sozinho; diminua o ritmo |
200
+ | `NextApiServerError` | Falha da API ou do provedor externo | 5xx / 1014, 9999 | 503 é repetido sozinho; persistindo, fale com o suporte |
201
+ | `NextApiConnectionError` | Rede, tempo esgotado ou redirecionamento | status 0 | Verifique a conexão; GETs já foram repetidos |
202
+
203
+ Todas trazem o status HTTP, o código da API, a mensagem, o corpo da resposta e o **request id**. Ao falar com o
204
+ suporte, mande o request id: ele localiza a requisição nos nossos logs.
205
+
206
+ ```python
207
+ import time
208
+ from sharpfy_nextapi import (NextApiError, NextApiNotFoundError, NextApiInsufficientCreditsError,
209
+ NextApiRateLimitError)
210
+
211
+ try:
212
+ empresa = nextapi.cnpj.consultar(cnpj)
213
+ except NextApiNotFoundError:
214
+ empresa = None
215
+ except NextApiInsufficientCreditsError as e:
216
+ log.warning("sem créditos (%s)", e.request_id)
217
+ except NextApiRateLimitError as e:
218
+ time.sleep(e.retry_after or 5)
219
+ except NextApiError as e: # qualquer outra falha do SDK
220
+ log.error("NextAPI %s/%s %s req=%s", e.status, e.code, e.message, e.request_id)
221
+ ```
222
+
223
+ ## Comportamento
224
+
225
+ **Novas tentativas.** Só requisições `GET` são repetidas, e só em falha transitória: `429`, `502`, `503`, `504` e
226
+ erro de rede. O cliente respeita o `Retry-After` da resposta (até 60 s); sem ele, espera de 0,5 s a 8 s, com
227
+ crescimento exponencial e variação aleatória. Os lotes (`POST`) **nunca** são repetidos sozinhos, porque consomem
228
+ créditos: numa falha, decida você se repete. O padrão é 2 novas tentativas; `max_retries=0` desliga.
229
+
230
+ **Tempo limite.** `timeout` por tentativa (padrão 30 s). Com novas tentativas, o tempo total pode passar disso.
231
+
232
+ **Validação local.** Entrada que a API recusaria com certeza nem sai do processo: vira
233
+ `NextApiValidationError` (status 0) antes da requisição. É o caso de CNPJ com tamanho ou dígitos verificadores errados,
234
+ lote vazio ou acima de 100, CEP sem 8 dígitos, raio menor ou igual a zero e latitude ou longitude fora da faixa.
235
+ CNPJ e CEP aceitam pontuação (`11.222.333/0001-81`, `01001-000`).
236
+
237
+ **CNPJ alfanumérico.** O formato novo da Receita (IN RFB 2.229/2024, a partir de julho de 2026) é aceito em todos os
238
+ métodos de CNPJ: `12.ABC.345/01DE-35` vira `12ABC34501DE35`, com letras em maiúsculas.
239
+
240
+ **Segurança.** A chave não aparece em logs, mensagens de erro nem na representação do cliente. O cliente não segue
241
+ redirecionamento, para a chave nunca ir para outro host, e só aceita `https` no `baseUrl` (`http` apenas para
242
+ `localhost`).
243
+
244
+ **Cabeçalhos enviados.** Além da autorização, cada requisição leva `User-Agent`, `X-NextApi-Client`
245
+ (`python/<versão>`) e `X-NextApi-Client-Info` (runtime, sistema e o seu `appInfo`). Servem para o suporte e para
246
+ medirmos o uso de cada versão; não carregam dado do seu negócio. O `appInfo` passa por um filtro: só
247
+ `A-Za-z0-9._/@+-`, até 64 caracteres.
248
+
249
+ **Reuso.** Crie um cliente e reutilize. Ele não guarda estado entre chamadas e pode ser usado por várias threads.
250
+
251
+ ## Sandbox
252
+
253
+ Com a chave `nxa_test_`, estes CNPJs provocam cada resposta da API, para você testar o tratamento de erro sem
254
+ gastar nada:
255
+
256
+ | CNPJ | Resposta |
257
+ |---|---|
258
+ | `99999991000125` | 404, não encontrado |
259
+ | `99999992000170` | 405 / 1004, sem créditos |
260
+ | `99999993000114` | 429 / 1003, limite por minuto |
261
+ | `99999994000169` | 503 / 1014, falha do provedor |
262
+ | `99999995000103` | sucesso depois de 8 s (consulta lenta) |
263
+ | `99999996000158` | 405 / 1012, exige plano pago |
264
+ | `99999997000100` | 401 / 1002, chave inválida |
265
+
266
+ O sandbox tem limite próprio de requisições por minuto e por dia, e os dados vêm de um subconjunto real: um CNPJ ou
267
+ CEP pode existir em produção e não no sandbox.
268
+
269
+ ## Testes
270
+
271
+ Os testes não usam rede: conferem cada método contra o contrato da API, em `contract/cases.json` (rota, parâmetros, corpo, respostas e erros).
272
+
273
+ ```bash
274
+ docker run --rm -v "$PWD":/src -w /src python:3.12 python -m unittest discover -s tests -v
275
+ ```
276
+
277
+ Com `NEXTAPI_SMOKE_KEY` definida (e `NEXTAPI_SMOKE_ENV=sandbox` ou `production`), roda também a fumaça contra a API
278
+ publicada, com os passos de `contract/smoke.json`.
279
+
280
+ ## Suporte e licença
281
+
282
+ Dúvidas e problemas: abra uma issue neste repositório ou escreva pelo [app.nextapi.com.br](https://app.nextapi.com.br),
283
+ com o request id do erro. Licença MIT.
@@ -0,0 +1,256 @@
1
+ # NextAPI para Python (`sharpfy-nextapi`)
2
+
3
+ SDK oficial da [NextAPI](https://nextapi.com.br) para Python 3.11+: CNPJ (inclusive alfanumérico), Simples Nacional, inscrições estaduais, conformidade, sócios, CEP com busca geográfica, pesquisa de empresas, localidades, mercado e créditos. Sem dependências: só a biblioteca padrão. As respostas são `dict` com tipos (`TypedDict`), prontas para `json.dumps` ou para o seu modelo.
4
+
5
+ ## Requisitos
6
+
7
+ - Python 3.11 ou mais recente (testado no 3.11 e no 3.15)
8
+ - Uma chave de API (veja abaixo)
9
+
10
+ ## Instalação
11
+
12
+ ```bash
13
+ pip install sharpfy-nextapi
14
+ ```
15
+
16
+ ## Chave de API
17
+
18
+ Crie a sua em [app.nextapi.com.br](https://app.nextapi.com.br). São dois tipos:
19
+
20
+ | Prefixo | Ambiente | Custo |
21
+ |---|---|---|
22
+ | `nxa_test_…` | Sandbox: dados de um subconjunto real, limites próprios e CNPJs de teste que provocam cada erro | Nenhum: nada é debitado |
23
+ | `nxa_live_…` | Produção | Créditos do seu plano |
24
+
25
+ O ambiente sai do prefixo da chave; o endereço da API é o mesmo. Guarde a chave na variável de ambiente
26
+ `NEXTAPI_KEY`, que o cliente lê quando você não passa a chave. **Nunca** a coloque no código, no repositório ou num
27
+ front-end: quem tem a chave consome os seus créditos.
28
+
29
+ ## Início rápido
30
+
31
+ ```python
32
+ from sharpfy_nextapi import NextApiClient
33
+
34
+ nextapi = NextApiClient() # lê NEXTAPI_KEY
35
+
36
+ empresa = nextapi.cnpj.consultar("11.222.333/0001-81")
37
+ print(empresa["razaoSocial"], empresa["situacaoCadastral"])
38
+ ```
39
+
40
+ ## Configuração
41
+
42
+ ```python
43
+ import os
44
+ from sharpfy_nextapi import NextApiClient
45
+
46
+ nextapi = NextApiClient(
47
+ os.environ["NEXTAPI_KEY"], # padrão: NEXTAPI_KEY
48
+ base_url="https://api.nextapi.com.br", # só https (http apenas para localhost)
49
+ timeout=15.0, # segundos, por tentativa; padrão 30
50
+ max_retries=3, # padrão 2; 0 desliga
51
+ app_info="minha-app/1.4.0", # identifica a sua aplicação
52
+ )
53
+ ```
54
+
55
+ | Parâmetro | Padrão | Efeito |
56
+ |---|---|---|
57
+ | `api_key` | `NEXTAPI_KEY` | Chave de API; o prefixo define o ambiente (`nextapi.environment`) |
58
+ | `base_url` | `https://api.nextapi.com.br` | Endereço da API |
59
+ | `timeout` | 30.0 | Tempo limite de cada tentativa, em segundos |
60
+ | `max_retries` | 2 | Novas tentativas em falha transitória, só em GET |
61
+ | `app_info` | — | Nome e versão da sua aplicação, nos cabeçalhos |
62
+ | `transport` | `urllib` | Transporte HTTP próprio (proxy, testes) |
63
+
64
+ ### Django, Flask, FastAPI
65
+
66
+ Crie o cliente uma vez, no carregamento do módulo:
67
+
68
+ <!-- readme-check: ignorar (depende do framework) -->
69
+ ```python
70
+ # servicos/nextapi.py
71
+ from sharpfy_nextapi import NextApiClient
72
+ nextapi = NextApiClient(app_info="erp/5.2")
73
+
74
+ # views.py
75
+ from servicos.nextapi import nextapi
76
+ def fornecedor(request, cnpj):
77
+ return JsonResponse(nextapi.cnpj.consultar(cnpj))
78
+ ```
79
+
80
+ O cliente é síncrono. Em código `async` (FastAPI, aiohttp), chame-o numa thread:
81
+ `await asyncio.to_thread(nextapi.cnpj.consultar, cnpj)`.
82
+
83
+ ## Exemplos
84
+
85
+ ### CNPJ
86
+
87
+ ```python
88
+ # Cadastro (1 crédito). tolerance_days: idade máxima aceita do dado em cache (0 a 45); 0 força tempo real.
89
+ empresa = nextapi.cnpj.consultar("11222333000181", tolerance_days=30)
90
+ ao_vivo = nextapi.cnpj.consultar_ao_vivo("11222333000181") # tempo real; exige plano que permita
91
+
92
+ simples = nextapi.cnpj.obter_simples("11222333000181")
93
+ ies = nextapi.cnpj.obter_inscricoes_estaduais("11222333000181")
94
+ conformidade = nextapi.cnpj.obter_conformidade("11222333000181") # sanções e dívida ativa
95
+ alfanumerico = nextapi.cnpj.consultar("12.ABC.345/01DE-35")
96
+ ```
97
+
98
+ ### Lotes (até 100 CNPJs)
99
+
100
+ ```python
101
+ lote = nextapi.cnpj.consultar_lote(["11222333000181", "45997418000153"]) # 1 crédito por CNPJ encontrado
102
+ simples_lote = nextapi.cnpj.obter_simples_lote(["11222333000181"])
103
+
104
+ # Mais de 100: divida em blocos. Lote nunca é repetido sozinho; decida você numa falha.
105
+ for i in range(0, len(todos), 100):
106
+ resultados.extend(nextapi.cnpj.consultar_lote(todos[i:i + 100]))
107
+ ```
108
+
109
+ ### Sócios e grupo econômico
110
+
111
+ ```python
112
+ rel = nextapi.cnpj.obter_relacionamentos("11222333000181", page=1, page_size=50)
113
+ for socio in rel.get("socios") or []:
114
+ # hashSocio só é estável quando vinculoVerificavel é True: não guarde os provisórios.
115
+ empresas = nextapi.socios.listar_empresas(socio["hashSocio"])
116
+ ```
117
+
118
+ ### CEP
119
+
120
+ ```python
121
+ cep = nextapi.ceps.consultar("01001-000")
122
+ por_rua = nextapi.ceps.buscar(uf="SP", nome_municipio="São Paulo", logradouro="Paulista")
123
+ raio = nextapi.ceps.buscar_proximos(latitude=-23.5505, longitude=-46.6333, raio_metro=500)
124
+ vizinhos = nextapi.ceps.buscar_proximos_do_cep("01001000", raio_metro=1000, page_size=100)
125
+ ```
126
+
127
+ ### Pesquisa de empresas, com paginação
128
+
129
+ ```python
130
+ from datetime import date
131
+
132
+ page = 1
133
+ while True:
134
+ pagina = nextapi.empresas.pesquisar(
135
+ uf="SP",
136
+ cnaes="1091101", # vários: separados por vírgula
137
+ data_abertura_inicio=date(2024, 1, 1),
138
+ page=page,
139
+ page_size=100,
140
+ )
141
+ for e in pagina["items"]:
142
+ print(e["cnpj"], e["razaoSocial"])
143
+ if page * pagina["pageSize"] >= pagina["total"]:
144
+ break
145
+ page += 1
146
+ ```
147
+
148
+ ### Localidades, mercado e créditos
149
+
150
+ ```python
151
+ estados = nextapi.estados.listar()
152
+ municipios = nextapi.municipios.listar(uf="MG", page_size=100)
153
+ bh = nextapi.municipios.obter_por_id(3106200)
154
+ cnaes = nextapi.cnaes.listar(page=1, page_size=50)
155
+
156
+ mercado = nextapi.mercado.obter_cnae("1091101", uf="SP", meses=12)
157
+ creditos = nextapi.creditos.consultar()
158
+ print(f"restam {creditos['totalRemainingCredits']} créditos")
159
+ ```
160
+
161
+ ## Erros
162
+
163
+ Toda falha vira uma exceção do SDK; a classe diz o que fazer, e o código detalha.
164
+
165
+ | Classe | Quando | Status / código | O que fazer |
166
+ |---|---|---|---|
167
+ | `NextApiAuthenticationError` | Chave ausente, inválida ou revogada | 401 / 1002, 400 / 1001 | Confira a chave e o ambiente |
168
+ | `NextApiInsufficientCreditsError` | Créditos do período acabaram | 405 / 1004, 1006 | Aguarde a renovação ou compre créditos avulsos |
169
+ | `NextApiPaidPlanRequiredError` | Recurso exige plano pago | 405 / 1012, 1005 | Mude de plano |
170
+ | `NextApiNotFoundError` | CNPJ, CEP ou município não existe | 404 / 1000 | Trate como resultado, não como falha |
171
+ | `NextApiValidationError` | Entrada recusada pela API ou pelo SDK | 400 / 1007, ou status 0 | Corrija a entrada; não repita |
172
+ | `NextApiRateLimitError` | Limite de requisições por minuto | 429 / 1003 | Já repetido sozinho; diminua o ritmo |
173
+ | `NextApiServerError` | Falha da API ou do provedor externo | 5xx / 1014, 9999 | 503 é repetido sozinho; persistindo, fale com o suporte |
174
+ | `NextApiConnectionError` | Rede, tempo esgotado ou redirecionamento | status 0 | Verifique a conexão; GETs já foram repetidos |
175
+
176
+ Todas trazem o status HTTP, o código da API, a mensagem, o corpo da resposta e o **request id**. Ao falar com o
177
+ suporte, mande o request id: ele localiza a requisição nos nossos logs.
178
+
179
+ ```python
180
+ import time
181
+ from sharpfy_nextapi import (NextApiError, NextApiNotFoundError, NextApiInsufficientCreditsError,
182
+ NextApiRateLimitError)
183
+
184
+ try:
185
+ empresa = nextapi.cnpj.consultar(cnpj)
186
+ except NextApiNotFoundError:
187
+ empresa = None
188
+ except NextApiInsufficientCreditsError as e:
189
+ log.warning("sem créditos (%s)", e.request_id)
190
+ except NextApiRateLimitError as e:
191
+ time.sleep(e.retry_after or 5)
192
+ except NextApiError as e: # qualquer outra falha do SDK
193
+ log.error("NextAPI %s/%s %s req=%s", e.status, e.code, e.message, e.request_id)
194
+ ```
195
+
196
+ ## Comportamento
197
+
198
+ **Novas tentativas.** Só requisições `GET` são repetidas, e só em falha transitória: `429`, `502`, `503`, `504` e
199
+ erro de rede. O cliente respeita o `Retry-After` da resposta (até 60 s); sem ele, espera de 0,5 s a 8 s, com
200
+ crescimento exponencial e variação aleatória. Os lotes (`POST`) **nunca** são repetidos sozinhos, porque consomem
201
+ créditos: numa falha, decida você se repete. O padrão é 2 novas tentativas; `max_retries=0` desliga.
202
+
203
+ **Tempo limite.** `timeout` por tentativa (padrão 30 s). Com novas tentativas, o tempo total pode passar disso.
204
+
205
+ **Validação local.** Entrada que a API recusaria com certeza nem sai do processo: vira
206
+ `NextApiValidationError` (status 0) antes da requisição. É o caso de CNPJ com tamanho ou dígitos verificadores errados,
207
+ lote vazio ou acima de 100, CEP sem 8 dígitos, raio menor ou igual a zero e latitude ou longitude fora da faixa.
208
+ CNPJ e CEP aceitam pontuação (`11.222.333/0001-81`, `01001-000`).
209
+
210
+ **CNPJ alfanumérico.** O formato novo da Receita (IN RFB 2.229/2024, a partir de julho de 2026) é aceito em todos os
211
+ métodos de CNPJ: `12.ABC.345/01DE-35` vira `12ABC34501DE35`, com letras em maiúsculas.
212
+
213
+ **Segurança.** A chave não aparece em logs, mensagens de erro nem na representação do cliente. O cliente não segue
214
+ redirecionamento, para a chave nunca ir para outro host, e só aceita `https` no `baseUrl` (`http` apenas para
215
+ `localhost`).
216
+
217
+ **Cabeçalhos enviados.** Além da autorização, cada requisição leva `User-Agent`, `X-NextApi-Client`
218
+ (`python/<versão>`) e `X-NextApi-Client-Info` (runtime, sistema e o seu `appInfo`). Servem para o suporte e para
219
+ medirmos o uso de cada versão; não carregam dado do seu negócio. O `appInfo` passa por um filtro: só
220
+ `A-Za-z0-9._/@+-`, até 64 caracteres.
221
+
222
+ **Reuso.** Crie um cliente e reutilize. Ele não guarda estado entre chamadas e pode ser usado por várias threads.
223
+
224
+ ## Sandbox
225
+
226
+ Com a chave `nxa_test_`, estes CNPJs provocam cada resposta da API, para você testar o tratamento de erro sem
227
+ gastar nada:
228
+
229
+ | CNPJ | Resposta |
230
+ |---|---|
231
+ | `99999991000125` | 404, não encontrado |
232
+ | `99999992000170` | 405 / 1004, sem créditos |
233
+ | `99999993000114` | 429 / 1003, limite por minuto |
234
+ | `99999994000169` | 503 / 1014, falha do provedor |
235
+ | `99999995000103` | sucesso depois de 8 s (consulta lenta) |
236
+ | `99999996000158` | 405 / 1012, exige plano pago |
237
+ | `99999997000100` | 401 / 1002, chave inválida |
238
+
239
+ O sandbox tem limite próprio de requisições por minuto e por dia, e os dados vêm de um subconjunto real: um CNPJ ou
240
+ CEP pode existir em produção e não no sandbox.
241
+
242
+ ## Testes
243
+
244
+ Os testes não usam rede: conferem cada método contra o contrato da API, em `contract/cases.json` (rota, parâmetros, corpo, respostas e erros).
245
+
246
+ ```bash
247
+ docker run --rm -v "$PWD":/src -w /src python:3.12 python -m unittest discover -s tests -v
248
+ ```
249
+
250
+ Com `NEXTAPI_SMOKE_KEY` definida (e `NEXTAPI_SMOKE_ENV=sandbox` ou `production`), roda também a fumaça contra a API
251
+ publicada, com os passos de `contract/smoke.json`.
252
+
253
+ ## Suporte e licença
254
+
255
+ Dúvidas e problemas: abra uma issue neste repositório ou escreva pelo [app.nextapi.com.br](https://app.nextapi.com.br),
256
+ com o request id do erro. Licença MIT.
@@ -0,0 +1,52 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "sharpfy-nextapi"
7
+ version = "0.2.0"
8
+ description = "SDK oficial da NextAPI para Python: CNPJ (inclusive alfanumérico), Simples Nacional, CEP, sócios e mercado. Sem dependências."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [
14
+ { name = "Sharpfy", email = "contato@sharpfy.com.br" }
15
+ ]
16
+ keywords = [
17
+ "nextapi",
18
+ "sharpfy",
19
+ "cnpj",
20
+ "receita-federal",
21
+ "simples-nacional",
22
+ "socios",
23
+ "compliance",
24
+ "consulta-cnpj"
25
+ ]
26
+ classifiers = [
27
+ "Development Status :: 4 - Beta",
28
+ "Intended Audience :: Developers",
29
+ "Operating System :: OS Independent",
30
+ "Programming Language :: Python :: 3",
31
+ "Programming Language :: Python :: 3.11",
32
+ "Programming Language :: Python :: 3.12",
33
+ "Programming Language :: Python :: 3.13",
34
+ "Programming Language :: Python :: 3.14",
35
+ "Programming Language :: Python :: 3.15",
36
+ "Topic :: Software Development :: Libraries :: Python Modules",
37
+ "Typing :: Typed",
38
+ ]
39
+ dependencies = []
40
+
41
+ [project.urls]
42
+ Homepage = "https://nextapi.com.br"
43
+ Documentation = "https://github.com/sharpfytecnologia/nextapi-sdk-python#readme"
44
+ Repository = "https://github.com/sharpfytecnologia/nextapi-sdk-python"
45
+ Issues = "https://github.com/sharpfytecnologia/nextapi-sdk-python/issues"
46
+
47
+ [tool.setuptools.packages.find]
48
+ where = ["."]
49
+ include = ["sharpfy_nextapi*"]
50
+
51
+ [tool.setuptools.package-data]
52
+ sharpfy_nextapi = ["py.typed"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,15 @@
1
+ """SDK oficial da NextAPI para Python (CNPJ, CEP, sócios, mercado). Sem dependências."""
2
+ from sharpfy_nextapi._validation import normalize_cep, normalize_cnpj
3
+ from sharpfy_nextapi._version import VERSION as __version__
4
+ from sharpfy_nextapi.client import NextApi, NextApiClient
5
+ from sharpfy_nextapi.errors import (ErrorCodes, NextApiAuthenticationError, NextApiConnectionError, NextApiError,
6
+ NextApiInsufficientCreditsError, NextApiNotFoundError,
7
+ NextApiPaidPlanRequiredError, NextApiRateLimitError, NextApiServerError,
8
+ NextApiValidationError)
9
+
10
+ __all__ = [
11
+ "NextApiClient", "NextApi", "ErrorCodes", "NextApiError", "NextApiAuthenticationError",
12
+ "NextApiInsufficientCreditsError", "NextApiPaidPlanRequiredError", "NextApiNotFoundError",
13
+ "NextApiValidationError", "NextApiRateLimitError", "NextApiServerError", "NextApiConnectionError",
14
+ "normalize_cnpj", "normalize_cep", "__version__",
15
+ ]
@@ -0,0 +1,40 @@
1
+ """Transporte HTTP sobre a biblioteca padrão (urllib), sem dependências."""
2
+ import ssl
3
+ import urllib.error
4
+ import urllib.request
5
+ from typing import Dict, Mapping, NamedTuple, Optional, Protocol
6
+
7
+
8
+ class Response(NamedTuple):
9
+ status: int
10
+ headers: Mapping[str, str]
11
+ body: bytes
12
+
13
+
14
+ class Transport(Protocol):
15
+ """Faz uma requisição e devolve a resposta, seja qual for o status. Erros de rede viram exceção (OSError)."""
16
+
17
+ def __call__(self, method: str, url: str, headers: Dict[str, str], body: Optional[bytes],
18
+ timeout: float) -> Response: ...
19
+
20
+
21
+ class _NoRedirect(urllib.request.HTTPRedirectHandler):
22
+ # urllib manda o cabeçalho Authorization junto para o destino do redirecionamento: não seguir.
23
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
24
+ return None
25
+
26
+
27
+ class UrllibTransport:
28
+ def __init__(self, ssl_context: Optional[ssl.SSLContext] = None):
29
+ context = ssl_context or ssl.create_default_context()
30
+ self._opener = urllib.request.build_opener(_NoRedirect(), urllib.request.HTTPSHandler(context=context))
31
+
32
+ def __call__(self, method, url, headers, body, timeout):
33
+ request = urllib.request.Request(url, data=body, headers=headers, method=method)
34
+ try:
35
+ with self._opener.open(request, timeout=timeout) as response:
36
+ return Response(response.status, {k.lower(): v for k, v in response.headers.items()}, response.read())
37
+ except urllib.error.HTTPError as error: # status >= 400 e redirecionamentos não seguidos
38
+ with error:
39
+ payload = error.read()
40
+ return Response(error.code, {k.lower(): v for k, v in (error.headers or {}).items()}, payload)