{"openapi":"3.0.3","info":{"title":"iaCDA -- API","version":"1.1","description":"Consulta, carga e eventos. A CARGA (POST /v1/cargas/{layout}) vira um lote da Importação, com as mesmas regras do arquivo; os layouts e campos aceitos estão em GET /v1/layouts. Autenticação OAuth2 client credentials: POST /oauth/token com client_id e client_secret (formulário ou Basic) e o token no cabeçalho Authorization: Bearer <token>. Valores monetários em reais; datas AAAA-MM-DD."},"servers":[{"url":"https://api.demonstracao.br.iacda.com.br"}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"/oauth/token","scopes":{"contribuintes":"Contribuintes (cadastro e contatos principais)","debitos":"Débitos e CDAs do contribuinte","resumo":"Resumo da carteira (totais por situação)","autenticidade":"Validação de certidões e CDAs pelo código","carga":"Envio de cadastros, débitos, pagamentos e parcelamentos (vira lote da Importação)","eventos":"Eventos da cobrança realizados (consulta e aviso ao sistema cliente)"}}}}}},"paths":{"/oauth/token":{"post":{"summary":"Emite o token de acesso (client_credentials)","responses":{"200":{"description":"access_token, token_type, expires_in"},"401":{"description":"invalid_client"}}}},"/v1/contribuintes":{"get":{"summary":"Lista/pesquisa contribuintes","security":[{"oauth2":["contribuintes"]}],"parameters":[{"name":"cpf_cnpj","in":"query","required":false,"description":"CPF ou CNPJ, com ou sem máscara","schema":{"type":"string"}},{"name":"nome","in":"query","required":false,"description":"parte do nome","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"itens por página (1 a 200, padrão 50)","schema":{"type":"string"}},{"name":"deslocamento","in":"query","required":false,"description":"quantos itens pular","schema":{"type":"string"}}],"responses":{"200":{"description":"lista paginada"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/contribuintes/{id_contribuinte}":{"get":{"summary":"Contribuinte, inscrições e endereço principal","security":[{"oauth2":["contribuintes"]}],"parameters":[{"name":"id_contribuinte","in":"path","required":true,"description":"identificador","schema":{"type":"string"}}],"responses":{"200":{"description":"objeto"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/contribuintes/{id_contribuinte}/debitos":{"get":{"summary":"Débitos do contribuinte (lançados e inscritos)","security":[{"oauth2":["debitos"]}],"parameters":[{"name":"id_contribuinte","in":"path","required":true,"description":"identificador","schema":{"type":"string"}},{"name":"situacao","in":"query","required":false,"description":"em_cobranca ou uma situação de pagamento (Vencida, A_Vencer, Parcelada, Paga, Compensada)","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"itens por página (1 a 200, padrão 50)","schema":{"type":"string"}},{"name":"deslocamento","in":"query","required":false,"description":"quantos itens pular","schema":{"type":"string"}}],"responses":{"200":{"description":"lista paginada. estagio_ciclo = estágio VIGENTE (marco atual da fase mais avançada cuja cobrança não foi revertida; vazio = não inscrito); <fase>_situacao = marco atual do episódio de cada fase (protesto_situacao, negativacao_situacao, ajuizamento_situacao...)"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/cdas/{num_cda}":{"get":{"summary":"Certidão de Dívida Ativa pelo número","security":[{"oauth2":["debitos"]}],"parameters":[{"name":"num_cda","in":"path","required":true,"description":"número da CDA","schema":{"type":"string"}}],"responses":{"200":{"description":"objeto"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/resumo":{"get":{"summary":"Totais da carteira por situação","security":[{"oauth2":["resumo"]}],"parameters":[],"responses":{"200":{"description":"objeto"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/autenticidade/{codigo}":{"get":{"summary":"Valida certidão ou CDA pelo código de autenticidade","security":[{"oauth2":["autenticidade"]}],"parameters":[{"name":"codigo","in":"path","required":true,"description":"código XXXX-XXXX-XXXX","schema":{"type":"string"}}],"responses":{"200":{"description":"objeto"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/layouts":{"get":{"summary":"Layouts de carga aceitos, na ordem de envio, com os campos","security":[{"oauth2":["carga"]}],"parameters":[],"responses":{"200":{"description":"objeto"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/cargas/{layout}":{"post":{"summary":"Envia registros de um layout (vira lote da Importação; o mesmo conteúdo reenviado não grava de novo)","security":[{"oauth2":["carga"]}],"parameters":[{"name":"layout","in":"path","required":true,"description":"sigla do layout (GET /v1/layouts)","schema":{"type":"string"}}],"responses":{"200":{"description":"situação do lote: lidos, novos, atualizados, recusados e os erros por registro"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["registros"],"properties":{"registros":{"type":"array","maxItems":5000,"items":{"type":"object"},"description":"um objeto por registro, com os campos do layout; valor em reais (número), data AAAA-MM-DD"},"confirmar":{"type":"boolean","default":true,"description":"false = fica 'Lido' para conferência na tela da Importação"},"tag":{"type":"string","description":"agrupador da carga (ex. migracao_2026)"}}}}}}}},"/v1/cargas/{id_lote}/situacao":{"get":{"summary":"Situação de uma carga enviada pela API","security":[{"oauth2":["carga"]}],"parameters":[{"name":"id_lote","in":"path","required":true,"description":"id devolvido no envio","schema":{"type":"string"}}],"responses":{"200":{"description":"objeto"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}},"/v1/eventos":{"get":{"summary":"Ações de cobrança realizadas no período (notificação, protesto, negativação, ajuizamento...)","security":[{"oauth2":["eventos"]}],"parameters":[{"name":"desde","in":"query","required":false,"description":"data inicial AAAA-MM-DD (obrigatória)","schema":{"type":"string"}},{"name":"ate","in":"query","required":false,"description":"data final AAAA-MM-DD (padrão: hoje)","schema":{"type":"string"}},{"name":"fase","in":"query","required":false,"description":"sigla da fase (NotOf, ProtTit, NegCtr, ExecFisc...)","schema":{"type":"string"}},{"name":"limite","in":"query","required":false,"description":"itens por página (1 a 200, padrão 50)","schema":{"type":"string"}},{"name":"deslocamento","in":"query","required":false,"description":"quantos itens pular","schema":{"type":"string"}}],"responses":{"200":{"description":"lista paginada; o mesmo evento é avisado por POST na URL do cliente quando o aviso está ligado (cabeçalho X-iaCDA-Assinatura: sha256=HMAC do corpo com o segredo do aviso)"},"401":{"description":"token ausente, inválido ou vencido"},"403":{"description":"escopo insuficiente"},"404":{"description":"não encontrado"},"429":{"description":"limite de chamadas por minuto"}}}}}}