{ "openapi": "3.1.0", "info": { "title": "CorpData API", "version": "1.0.0", "summary": "Dados cadastrais de empresas brasileiras (Receita Federal) e enriquecimento por bureau.", "description": "API para consultar, segmentar e exportar dados de CNPJ da base pública da Receita Federal,\nalém de enriquecer cadastros com dados de bureau parceiro.\n\n## Autenticação\nEnvie sua chave no header `Authorization: Bearer cd_live_...` (ou `X-API-Key`).\nGere e revogue chaves em Integrações, no painel. A chave é exibida uma única vez.\n\n## Créditos\nCada chamada que entrega dado consome créditos do seu plano:\n- Registro de empresa (busca ou consulta): **1 crédito** por registro entregue\n- Lead exportado no mailing: **1 crédito** por lead\n- Enriquecimento por bureau: **5 créditos** por CNPJ\n- Consulta de pessoa física (CPF ou telefone): **15 créditos** por consulta\n\nContagem (`/empresas?apenas_total=true`) **não consome crédito** — use para dimensionar antes de gastar.\nVocê só paga pelo que é efetivamente entregue: job que falha não cobra, e consultar o status\nvárias vezes cobra uma vez só.\n\n## Limites\n- 120 requisições por minuto, por chave\n- Limite diário conforme o seu plano (veja os cabeçalhos `X-RateLimit-*` na resposta)\n\n## Escopos\n- `empresas:read` — Consultar e buscar empresas\n- `mailing:read` — Estimar volume e acompanhar exportações\n- `mailing:export` — Gerar exportações de mailing (consome créditos)\n- `enriquecimento:read` — Enriquecer CNPJ pelo bureau (consome créditos)\n- `pessoas:read` — Consultar pessoa física por CPF (consome créditos)\n- `credito:read` — Relatório de crédito por CPF/CNPJ (consome créditos)\n- `sms:otp` — Enviar e conferir códigos de verificação por SMS (consome créditos de SMS)\n\nUma chave só acessa o que o escopo dela permite; caso contrário a resposta é `403 SEM_ESCOPO`.", "contact": { "name": "Suporte CorpData", "url": "https://corpdata.com.br" } }, "servers": [ { "url": "https://corpdata.com.br/api/v1", "description": "Produção" } ], "security": [ { "ChaveApi": [] } ], "tags": [ { "name": "Empresas", "description": "Consulta e segmentação da base da Receita Federal." }, { "name": "Mailing", "description": "Exportação assíncrona de listas." }, { "name": "Enriquecimento", "description": "Dados complementares por bureau parceiro." }, { "name": "SMS", "description": "Códigos de verificação (OTP) por SMS, pagos com créditos de SMS." }, { "name": "Pessoa física", "description": "Consulta de CPF para KYC e análise de crédito. Liberação individual, por contrato." } ], "components": { "securitySchemes": { "ChaveApi": { "type": "http", "scheme": "bearer", "description": "Chave de API do CorpData, no formato `cd_live_...`." } }, "schemas": { "Erro": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } }, "Empresa": { "type": "object", "description": "Registro cadastral da Receita Federal. Os campos disponíveis variam conforme o cadastro.", "properties": { "cnpj": { "type": "string", "example": "00000000000191" }, "razao_social": { "type": "string" }, "nome_fantasia": { "type": "string" }, "situacao_cadastral": { "type": "string", "description": "Código; a descrição por extenso vem em `situacao_descricao`." }, "situacao_descricao": { "type": "string", "example": "Ativa" }, "cnae": { "type": "string" }, "cnae_descricao": { "type": "string" }, "natureza_juridica": { "type": "string" }, "natureza_descricao": { "type": "string" }, "porte": { "type": "string" }, "porte_descricao": { "type": "string" }, "capital_social": { "type": "number" }, "data_abertura": { "type": "string", "format": "date" }, "uf": { "type": "string", "example": "ES" }, "municipio": { "type": "string" }, "bairro": { "type": "string" }, "cep": { "type": "string" }, "logradouro": { "type": "string" }, "telefone": { "type": "string" }, "email": { "type": "string" } } }, "Paginacao": { "type": "object", "properties": { "pagina": { "type": "integer", "example": 1 }, "limite": { "type": "integer", "example": 50 }, "retornados": { "type": "integer", "description": "Quantidade nesta página — é o que foi cobrado." }, "total": { "type": "integer", "description": "Total de empresas que atendem ao filtro." } } } } }, "paths": { "/empresas": { "get": { "tags": [ "Empresas" ], "operationId": "buscarEmpresas", "summary": "Buscar empresas por filtros", "description": "Segmenta a base da Receita Federal. Exige **ao menos um filtro**.\n\n**Custo:** 1 crédito por registro entregue. Com `apenas_total=true`, devolve só a contagem e **não cobra**.\n\nFiltros de múltipla escolha são repetidos na query string: `?ufs=ES&ufs=SP`.\n\n**Escopo:** `empresas:read`", "parameters": [ { "name": "ufs", "in": "query", "schema": { "type": "string" }, "example": "ES", "description": "UF. Repita para várias." }, { "name": "municipios", "in": "query", "schema": { "type": "string" }, "description": "Município. Repita para vários." }, { "name": "bairros", "in": "query", "schema": { "type": "string" } }, { "name": "ddds", "in": "query", "schema": { "type": "string" }, "example": "27" }, { "name": "cnaes", "in": "query", "schema": { "type": "string" }, "example": "6201501", "description": "CNAE principal." }, { "name": "cnaes_secundarios", "in": "query", "schema": { "type": "string" } }, { "name": "naturezas", "in": "query", "schema": { "type": "string" } }, { "name": "situacao_cadastral", "in": "query", "schema": { "type": "string" }, "example": "02", "description": "Com zero à esquerda. `02` = ativa." }, { "name": "portes", "in": "query", "schema": { "type": "string" } }, { "name": "mei", "in": "query", "schema": { "type": "boolean" } }, { "name": "simples", "in": "query", "schema": { "type": "boolean" } }, { "name": "abertura_de", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "abertura_ate", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "com_telefone", "in": "query", "schema": { "type": "boolean" } }, { "name": "com_telefone_movel", "in": "query", "schema": { "type": "boolean" } }, { "name": "com_email", "in": "query", "schema": { "type": "boolean" } }, { "name": "divida", "in": "query", "schema": { "type": "boolean" }, "description": "true = apenas com dívida ativa; false = apenas sem." }, { "name": "capital_min", "in": "query", "schema": { "type": "number" } }, { "name": "capital_max", "in": "query", "schema": { "type": "number" } }, { "name": "apenas_total", "in": "query", "schema": { "type": "boolean" }, "description": "Só a contagem, sem consumir crédito." }, { "name": "limite", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }, { "name": "pagina", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 } } ], "responses": { "200": { "description": "Registros encontrados (ou apenas o total).", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "array", "items": { "$ref": "#/components/schemas/Empresa" } }, "paginacao": { "$ref": "#/components/schemas/Paginacao" }, "total": { "type": "integer", "description": "Presente quando `apenas_total=true`." }, "aproximado": { "type": "boolean", "description": "true quando a contagem é estimada (base de 70M+)." }, "creditos_consumidos": { "type": "integer" } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/empresas/{cnpj}": { "get": { "tags": [ "Empresas" ], "operationId": "consultarEmpresa", "summary": "Consultar uma empresa pelo CNPJ", "description": "Ficha cadastral completa. O CNPJ é validado pelos dígitos verificadores antes de consultar a base.\n\n**Custo:** 1 crédito. Reconsultar o mesmo CNPJ no mesmo dia não cobra novamente.\n\n**Escopo:** `empresas:read`", "parameters": [ { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string" }, "example": "00000000000191", "description": "Com ou sem pontuação." } ], "responses": { "200": { "description": "Ficha da empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "$ref": "#/components/schemas/Empresa" }, "creditos_consumidos": { "type": "integer", "example": 1 } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Recurso não encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/mailing": { "post": { "tags": [ "Mailing" ], "operationId": "criarExportacao", "summary": "Criar exportação de mailing", "description": "Cria um job assíncrono de exportação e devolve `job_id`.\nAcompanhe em `GET /mailing/{job_id}`; ao concluir, o retorno traz `arquivo_url`.\n\n**Custo:** o saldo é conferido aqui, mas a cobrança ocorre **na conclusão**, pela quantidade\nefetivamente entregue — job que falha não cobra.\n\n**Escopo:** `mailing:export`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filtros", "quantidade" ], "properties": { "filtros": { "type": "object", "description": "Mesmos filtros de `GET /empresas`.", "example": { "ufs": [ "ES" ], "situacao_cadastral": [ "02" ], "com_telefone": true } }, "quantidade": { "type": "integer", "minimum": 1, "maximum": 50000, "example": 1000 }, "formato": { "type": "string", "enum": [ "csv", "xlsx" ], "default": "csv" } } } } } }, "responses": { "200": { "description": "Job criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "example": "processando" }, "quantidade_solicitada": { "type": "integer" }, "formato": { "type": "string" }, "acompanhar_em": { "type": "string" } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/mailing/{job_id}": { "get": { "tags": [ "Mailing" ], "operationId": "statusExportacao", "summary": "Status da exportação", "description": "Consulte periodicamente até `status = concluido`; então baixe `arquivo_url`.\n\n**Custo:** 1 crédito por lead entregue, cobrado uma única vez — o polling não duplica.\n\n**Escopo:** `mailing:read`", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Situação do job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "enum": [ "processando", "concluido", "erro" ] }, "progresso": { "type": "integer", "minimum": 0, "maximum": 100 }, "registros": { "type": "integer" }, "arquivo_url": { "type": [ "string", "null" ], "description": "Disponível quando concluído." }, "erro": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Recurso não encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/mailing/{job_id}/arquivo": { "get": { "tags": [ "Mailing" ], "operationId": "baixarExportacao", "summary": "Baixar o arquivo da exportação", "description": "Devolve o arquivo da exportação concluída (ZIP contendo o CSV ou XLSX).\n\nDisponível quando `GET /mailing/{job_id}` retornar `status: concluido`.\nO campo `arquivo_url` daquela resposta já aponta para cá.\n\n**Custo:** nenhum — a exportação foi cobrada na conclusão do job.\n\nA resposta é binária: use `-o arquivo.zip` no curl ou trate como stream.\n\n**Escopo:** `mailing:read`", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Arquivo da exportação.", "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Recurso não encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/enriquecimento/{cnpj}": { "get": { "tags": [ "Enriquecimento" ], "operationId": "enriquecerEmpresa", "summary": "Enriquecer CNPJ com dados de bureau", "description": "Complementa a ficha da Receita com dados do bureau parceiro: porte e operação,\natividades secundárias, complementos cadastrais, quadro societário ampliado e sinais de risco.\n\n**Custo:** 5 créditos.\n\nAceita **apenas CNPJ**. Dados pessoais de terceiros são descartados no servidor por allowlist;\no CPF de sócio vem completo (`socios[].cpf`). Requer credenciamento LGPD aprovado na sua conta.\n\n**Escopo:** `enriquecimento:read`", "parameters": [ { "name": "cnpj", "in": "path", "required": true, "schema": { "type": "string" }, "example": "00000000000191" } ], "responses": { "200": { "description": "Dados complementares.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "description": "Blocos normalizados por allowlist." }, "creditos_consumidos": { "type": "integer", "example": 5 } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso. · Credenciamento LGPD pendente de aprovação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Recurso não encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "503": { "description": "API temporariamente indisponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/sms/otp": { "post": { "tags": [ "SMS" ], "operationId": "enviarOtpSms", "summary": "Enviar código de verificação por SMS", "description": "Gera um código numérico, envia por SMS ao celular e devolve o `id` do envio. O código nunca volta na resposta.\n\nProteções: até 1 código a cada 30 s e 5 por hora para o mesmo celular. Só celulares (DDD + 9 dígitos).\n\n**Custo:** 1 crédito de SMS por código. Falha de entrega devolve o crédito.\n\n**Escopo:** `sms:otp`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "celular" ], "properties": { "celular": { "type": "string", "example": "11988887777", "description": "Com ou sem +55 e máscara." }, "empresa": { "type": "string", "maxLength": 30, "example": "Minha Loja", "description": "Aparece no início do SMS (sem acentos)." }, "digitos": { "type": "integer", "minimum": 4, "maximum": 8, "default": 6 }, "validade_minutos": { "type": "integer", "minimum": 1, "maximum": 15, "default": 5 } } } } } }, "responses": { "200": { "description": "Código enviado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Envie junto com o código em /sms/otp/verificar." }, "expira_em": { "type": "string", "format": "date-time" }, "creditos_consumidos": { "type": "integer", "example": 1 } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido. · Muitos códigos para o mesmo celular: aguarde 30 segundos (máximo de 5 por hora).", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "502": { "description": "Serviço de SMS indisponível no momento. Nada foi cobrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/sms/otp/verificar": { "post": { "tags": [ "SMS" ], "operationId": "verificarOtpSms", "summary": "Conferir o código digitado", "description": "Confere o código de um envio. Cada código aceita 5 tentativas, expira no prazo pedido e vale uma vez só.\n\n**Custo:** sem custo. **Escopo:** `sms:otp`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "codigo" ], "properties": { "id": { "type": "string", "format": "uuid" }, "codigo": { "type": "string", "example": "123456" } } } } } }, "responses": { "200": { "description": "Resultado da conferência.", "content": { "application/json": { "schema": { "type": "object", "properties": { "valido": { "type": "boolean" }, "motivo": { "type": "string", "enum": [ "CODIGO_INCORRETO", "EXPIRADO", "TENTATIVAS_ESGOTADAS", "JA_UTILIZADO" ], "description": "Presente quando `valido` é false." }, "tentativas_restantes": { "type": "integer" } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Recurso não encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/credito/consultar": { "post": { "tags": [ "Risco de crédito" ], "operationId": "consultarCredito", "summary": "Relatório de crédito (CPF ou CNPJ)", "description": "Relatório de crédito do bureau: negativações (Pefin/Refin), protestos, cheques sem fundo,\ndívidas vencidas, consultas de mercado recentes e quadro societário. Complementa `/pessoas` e\n`/enriquecimento` (cadastro e contato) com a visão de **risco** — o dossiê unificado.\n\n**Por que POST:** CPF/CNPJ não trafega em URL — caminho de requisição fica em log de servidor, proxy e CDN. O documento vai no corpo.\n\n**Custo:** 10 créditos por documento por mês: repetir o mesmo documento no mês não cobra de novo, e dentro de 7 dias a resposta vem do cache.\n\nBlocos pessoais do titular (filiação etc.) nunca saem pela API.\n\n**Escopo:** `credito:read`", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documento" ], "properties": { "documento": { "type": "string", "description": "CPF (11 dígitos) ou CNPJ (14 dígitos), só números.", "example": "00000000000191" }, "uf": { "type": "string", "description": "Opcional; o relatório é nacional.", "example": "SP" } } } } } }, "responses": { "200": { "description": "Relatório normalizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "description": "tipo (CPF|CNPJ), documento, nome, situacao, nadaConsta, restricoes[], pefins[], refins[], dividasVencidas[], protestos[], cheques[], participacoes[] (PF), socios[]/administradores[] (PJ), consultasMercado[], consultasCreditoMensal[]." }, "creditos_consumidos": { "type": "integer", "example": 10 } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Recurso não encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "502": { "description": "Serviço de consulta indisponível no momento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "503": { "description": "API temporariamente indisponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/pessoas/consultar": { "post": { "tags": [ "Pessoa física" ], "operationId": "consultarPessoa", "summary": "Consultar pessoa (CPF ou telefone)", "description": "Consulta de pessoa física por **CPF** ou por **telefone** (busca reversa: telefone → dono), para KYC, análise de crédito e finalidades correlatas.\n\n**Acesso:** exige o escopo `pessoas:read` **e** liberação individual da sua chave.\nTer o escopo não basta — a liberação é comercial e feita caso a caso.\n\n**Por que POST e não `GET /pessoas/{cpf}`:** CPF não trafega em URL. O caminho da\nrequisição fica registrado em log de servidor, proxy, CDN e no header `Referer` —\nlugares onde dado pessoal não deve estar em claro. No corpo, ele fica na conexão.\n\n**Finalidade** define o que volta na resposta. Cada finalidade libera um conjunto de\ncampos, contratado com você — não é o mesmo para todos os clientes:\n\n- `ANALISE_CREDITO` — Análise de crédito: Avaliação de risco para concessão de crédito ou limite.\n- `KYC_CADASTRO` — Cadastro (KYC): Conferência cadastral e conheça-seu-cliente.\n- `COBRANCA_DIVIDA_PROPRIA` — Cobrança de dívida própria: Localização de devedor de dívida da própria organização.\n- `PREVENCAO_FRAUDE` — Prevenção à fraude: Verificação de indícios de fraude em cadastro ou transação.\n\n**Justificativa** é opcional. Quando enviada, vai para a trilha de auditoria e deve ter\nao menos 15 caracteres, sem CPF, telefone ou e-mail (é campo livre, não depósito de dado\npessoal — e um número de 8+ dígitos é lido como telefone). Se você não enviar (ou enviar\nalgo inválido), a consulta usa automaticamente a **justificativa padrão da sua conta** e,\nna falta dela, um texto padrão da finalidade — a chamada nunca falha por causa deste campo.\n\n**Custo:** 15 créditos por consulta. Cobra a cada chamada, inclusive do mesmo CPF.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "finalidade" ], "description": "Envie `cpf` OU `telefone` (busca reversa: telefone → dono). Se vier CPF, o telefone é ignorado.", "properties": { "cpf": { "type": "string", "description": "CPF, com ou sem pontuação. Dígitos verificadores conferidos. Use CPF **ou** telefone.", "example": "12345678909" }, "telefone": { "type": "string", "description": "Telefone (DDD + número, 10 ou 11 dígitos) para busca reversa. Alternativa ao CPF — mesmo custo e finalidades.", "example": "11987654321" }, "finalidade": { "type": "string", "description": "Código da finalidade contratada. Se omitida — ou se você informar um código que a sua chave não tem —, usa automaticamente a mais ampla que a sua chave permite (nunca além do contratado). Uma finalidade válida e explícita é sempre honrada.", "example": "ANALISE_CREDITO" }, "justificativa": { "type": "string", "maxLength": 400, "description": "Opcional. Motivo da consulta, para a auditoria. ≥15 caracteres, sem CPF/telefone/e-mail (número de 8+ dígitos é lido como telefone). Se ausente ou inválida, usa a justificativa padrão da conta ou o texto padrão da finalidade — nunca derruba a chamada.", "example": "Proposta de credito em analise" } } } } } }, "responses": { "200": { "description": "Dossiê com os campos que a finalidade libera.", "content": { "application/json": { "schema": { "type": "object", "properties": { "dados": { "type": "object", "description": "Blocos liberados pela finalidade. Bloco não liberado fica AUSENTE da resposta — ausência significa 'não contratado', não 'não encontrado'.", "properties": { "finalidade": { "type": "string", "example": "ANALISE_CREDITO" }, "blocos": { "type": "array", "items": { "type": "string" }, "example": [ "identificacao", "financeiro" ] }, "identificacao": { "type": "object", "description": "Dados de identificação liberados pela finalidade contratada.", "properties": { "nomeCompleto": { "type": "string", "example": "Maria da Silva" }, "cpf": { "type": "string", "example": "123.456.789-09" }, "dataNascimento": { "type": "string", "description": "Data completa, quando disponível.", "example": "23/04/1987" }, "nascimentoAnoMes": { "type": "string", "description": "Campo legado mantido para compatibilidade.", "example": "04/1987" }, "statusReceita": { "type": "string", "example": "REGULAR" }, "estadoCivil": { "type": "string" }, "sexo": { "type": "string" } } }, "consultadoEm": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso. · Consulta de pessoa física não habilitada para esta chave. Fale com o seu contato comercial. · Esta finalidade não está contratada para a sua chave.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Sem dados para este CPF nesta finalidade.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Finalidade inválida. Veja as finalidades aceitas na documentação. · CPF inválido (dígitos verificadores não conferem).", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "502": { "description": "Serviço de consulta indisponível no momento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "503": { "description": "API temporariamente indisponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/pessoas/consultar-async": { "post": { "tags": [ "Pessoa física" ], "operationId": "consultarPessoaAsync", "summary": "Consultar CPF (assíncrono)", "description": "Abre a consulta e devolve um `job_id` na hora (milissegundos), sem esperar o bureau.\nO resultado sai depois em `GET /pessoas/jobs/{job_id}`.\n\nPara volume: dispare várias consultas sem prender uma conexão em cada, depois colete.\nAs mesmas travas da consulta síncrona valem aqui. Criar o job **não** consome crédito;\na cobrança ocorre quando o job é processado, uma única vez.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "finalidade" ], "description": "Envie `cpf` OU `telefone` (busca reversa: telefone → dono). Se vier CPF, o telefone é ignorado.", "properties": { "cpf": { "type": "string", "description": "CPF, com ou sem pontuação. Dígitos verificadores conferidos. Use CPF **ou** telefone.", "example": "12345678909" }, "telefone": { "type": "string", "description": "Telefone (DDD + número, 10 ou 11 dígitos) para busca reversa. Alternativa ao CPF — mesmo custo e finalidades.", "example": "11987654321" }, "finalidade": { "type": "string", "description": "Código da finalidade contratada. Se omitida — ou se você informar um código que a sua chave não tem —, usa automaticamente a mais ampla que a sua chave permite (nunca além do contratado). Uma finalidade válida e explícita é sempre honrada.", "example": "ANALISE_CREDITO" }, "justificativa": { "type": "string", "maxLength": 400, "description": "Opcional. Motivo da consulta, para a auditoria. ≥15 caracteres, sem CPF/telefone/e-mail (número de 8+ dígitos é lido como telefone). Se ausente ou inválida, usa a justificativa padrão da conta ou o texto padrão da finalidade — nunca derruba a chamada.", "example": "Proposta de credito em analise" } } } } } }, "responses": { "200": { "description": "Job criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string" }, "status": { "type": "string", "example": "pendente" }, "retry_after": { "type": "integer", "example": 2 }, "resultado_em": { "type": "string", "example": "/api/v1/pessoas/jobs/JOB_ID" } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso. · Consulta de pessoa física não habilitada para esta chave. Fale com o seu contato comercial. · Esta finalidade não está contratada para a sua chave.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Sem dados para este CPF nesta finalidade.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Finalidade inválida. Veja as finalidades aceitas na documentação. · CPF inválido (dígitos verificadores não conferem).", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "502": { "description": "Serviço de consulta indisponível no momento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "503": { "description": "API temporariamente indisponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/pessoas/jobs/{job_id}": { "get": { "tags": [ "Pessoa física" ], "operationId": "obterJobPessoa", "summary": "Resultado da consulta assíncrona", "description": "Estado e resultado de um job criado em `/pessoas/consultar-async`.\n\nA **primeira** chamada que encontra o job pendente é quem executa a consulta — essa\nabsorve o tempo do bureau; as demais leem o resultado pronto. Refaça após `retry_after`\nsegundos enquanto o status for `pendente` ou `processando`.\n\n`status = concluido` traz `dados` (o dossiê). O resultado é entregue **uma vez** e apagado:\nguarde-o do seu lado. O crédito é cobrado no processamento, nunca duas vezes.", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Estado do job. Verifique `status`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pendente", "processando", "concluido", "erro" ] }, "job_id": { "type": "string" }, "dados": { "type": "object", "description": "Presente quando status = concluido." }, "retry_after": { "type": "integer", "description": "Presente enquanto não concluído." }, "erro": { "type": "object", "description": "Presente quando status = erro." } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Recurso não encontrado.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } }, "/pessoas/lote": { "post": { "tags": [ "Pessoa física" ], "operationId": "consultarPessoasLote", "summary": "Consultar vários CPFs", "description": "Mesma consulta, vários CPFs numa chamada. Feito para quem processa fila.\n\n**A resposta é sempre 200**, com um item por CPF e o `status` de cada um. Um CPF\ninválido no meio do lote não derruba os outros: você recebe exatamente quais\nfalharam e por quê, sem precisar reprocessar tudo.\n\nCPF rejeitado na validação **não consome crédito** — não chegou a virar consulta.\n\n**Custo:** 15 créditos por CPF consultado com sucesso; duplicata no mesmo lote cobra uma vez só.\n\nO tamanho máximo do lote é definido no seu contrato (**padrão 100 CPFs por chamada**). Acima\ndele a resposta é `422 PARAMETRO_INVALIDO` informando o teto.\n\nA finalidade e a justificativa valem para o lote inteiro.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "cpfs", "finalidade", "justificativa" ], "properties": { "cpfs": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "CPFs a consultar. Duplicatas são removidas e cobradas uma vez só." }, "finalidade": { "type": "string", "example": "ANALISE_CREDITO" }, "justificativa": { "type": "string", "minLength": 15, "maxLength": 400 } } } } } }, "responses": { "200": { "description": "Resultado por CPF. Verifique o `status` de cada item.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resumo": { "type": "object", "properties": { "enviados": { "type": "integer", "example": 50 }, "consultados": { "type": "integer", "example": 48 }, "com_erro": { "type": "integer", "example": 2 }, "creditos": { "type": "integer", "example": 720 } } }, "itens": { "type": "array", "items": { "type": "object", "properties": { "cpf": { "type": "string", "description": "CPF completo, formatado.", "example": "123.456.789-09" }, "status": { "type": "string", "enum": [ "ok", "erro" ] }, "dados": { "type": "object", "description": "Presente quando status = ok." }, "erro": { "type": "object", "description": "Presente quando status = erro.", "properties": { "code": { "type": "string" }, "mensagem": { "type": "string" } } } } } } } } } } }, "401": { "description": "Envie sua chave em Authorization: Bearer . · Chave de API inválida.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "402": { "description": "Créditos insuficientes para esta operação.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "403": { "description": "Sua chave não tem permissão para este recurso. · Consulta de pessoa física não habilitada para esta chave. Fale com o seu contato comercial. · Esta finalidade não está contratada para a sua chave.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "404": { "description": "Sem dados para este CPF nesta finalidade.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "422": { "description": "Finalidade inválida. Veja as finalidades aceitas na documentação. · CPF inválido (dígitos verificadores não conferem). · Parâmetros inválidos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "429": { "description": "Muitas requisições. Tente novamente em alguns segundos. · Limite diário do seu plano atingido.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "500": { "description": "Erro interno. Tente novamente.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "502": { "description": "Serviço de consulta indisponível no momento.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } }, "503": { "description": "API temporariamente indisponível.", "content": { "application/json": { "schema": { "type": "object", "required": [ "erro" ], "properties": { "erro": { "type": "object", "required": [ "code", "mensagem" ], "properties": { "code": { "type": "string", "enum": [ "SEM_CHAVE", "CHAVE_INVALIDA", "CHAVE_REVOGADA", "SEM_ESCOPO", "CREDENCIAMENTO_PENDENTE", "NAO_ENCONTRADO", "PARAMETRO_INVALIDO", "LIMITE_MINUTO", "LIMITE_DIARIO", "SEM_CREDITOS", "API_DESATIVADA", "ERRO_INTERNO", "PF_NAO_HABILITADA", "FINALIDADE_INVALIDA", "FINALIDADE_NAO_CONTRATADA", "JUSTIFICATIVA_INVALIDA", "CPF_INVALIDO", "SEM_DADOS", "FORNECEDOR_INDISPONIVEL", "AUDITORIA_INDISPONIVEL", "LIMITE_OTP", "SMS_INDISPONIVEL" ], "description": "Código estável — programe em cima dele, não da mensagem." }, "mensagem": { "type": "string" }, "detalhe": { "type": "string" } } } } } } } } } } } } }