{"openapi":"3.1.0","info":{"title":"Adimple API","version":"1.0.0","description":"Consulta de crédito, cobrança e negativação para qualquer empresa e qualquer sistema de gestão (ERP, PDV, sistema de academia, escola…). Autenticação: `Authorization: Bearer adm_live_...` (crie a chave em Painel → Integrações). Dados pessoais vão SEMPRE no corpo (nunca na URL). Valores em centavos; datas AAAA-MM-DD. Webhooks são assinados: `Adimple-Signature: t=<unix>,v1=<hex HMAC-SHA256(segredo, \"<t>.<corpo>\")>`."},"servers":[{"url":"/v1"}],"security":[{"chave":[]}],"tags":[{"name":"Dívidas"},{"name":"Devedores"},{"name":"Consultas"},{"name":"Carteira"}],"paths":{"/debts":{"post":{"tags":["Dívidas"],"summary":"Cria uma dívida (e o devedor), opcionalmente já na régua","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Identificador único da operação (8 a 120 caracteres). Repetir com o mesmo corpo devolve a mesma resposta (cabeçalho Idempotent-Replayed: true), sem duplicar.","schema":{"type":"string","minLength":8,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewDebt"}}}},"responses":{"201":{"description":"Criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debt"}}}},"400":{"description":"Sem Idempotency-Key ou JSON inválido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Título ou external_ref já existe (duplicate_debt)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Dívidas"],"summary":"Lista dívidas","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["rascunho","em_regua","aguardando_prazo","negativando","negativada","erro_negativacao","baixa_pendente","baixada","erro_baixa","paga","cancelada"]}},{"name":"external_ref","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Página de dívidas","content":{"application/json":{"schema":{"type":"object","required":["data","page","per_page","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Debt"}},"page":{"type":"integer"},"per_page":{"type":"integer"},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/debts/{id}":{"get":{"tags":["Dívidas"],"summary":"Detalhe da dívida","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Dívida","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debt"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/debts/{id}/negativate":{"post":{"tags":["Dívidas"],"summary":"Solicita a negativação (confere as regras do CDC art. 43 e debita créditos)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Identificador único da operação (8 a 120 caracteres). Repetir com o mesmo corpo devolve a mesma resposta (cabeçalho Idempotent-Replayed: true), sem duplicar.","schema":{"type":"string","minLength":8,"maxLength":120}}],"responses":{"202":{"description":"Solicitada; o envio ao birô é assíncrono (webhook debt.negativated)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debt"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo de créditos insuficiente (insufficient_balance)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/debts/{id}/payments":{"post":{"tags":["Dívidas"],"summary":"Informa pagamento. Quitada e negativada → baixa pedida na hora (Súmula 548)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Identificador único da operação (8 a 120 caracteres). Repetir com o mesmo corpo devolve a mesma resposta (cabeçalho Idempotent-Replayed: true), sem duplicar.","schema":{"type":"string","minLength":8,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewPayment"}}}},"responses":{"201":{"description":"Pagamento registrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debt"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/debts/{id}/clear":{"post":{"tags":["Dívidas"],"summary":"Retira a negativação sem pagamento (acordo, erro de cadastro…)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Identificador único da operação (8 a 120 caracteres). Repetir com o mesmo corpo devolve a mesma resposta (cabeçalho Idempotent-Replayed: true), sem duplicar.","schema":{"type":"string","minLength":8,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","enum":["acordo","refinanciamento","erro_cadastro","decisao_judicial","obito_devedor","pedido_empresa"]}}}}}},"responses":{"202":{"description":"Baixa solicitada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debt"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/debts/{id}/cancel":{"post":{"tags":["Dívidas"],"summary":"Cancela a dívida (se negativada, pede a baixa)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Identificador único da operação (8 a 120 caracteres). Repetir com o mesmo corpo devolve a mesma resposta (cabeçalho Idempotent-Replayed: true), sem duplicar.","schema":{"type":"string","minLength":8,"maxLength":120}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","minLength":3,"maxLength":300}}}}}},"responses":{"200":{"description":"Cancelada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debt"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/embed-sessions":{"post":{"tags":["Dívidas"],"summary":"\"Ver no Adimple\": link de uso único (2 min) para o painel somente leitura da empresa","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"debt_id":{"type":"string","format":"uuid","description":"Abre direto nesta dívida (senão, a lista)"}}}}}},"responses":{"201":{"description":"Abra a url numa nova aba (ou iframe de origem autorizada)","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"expires_in":{"type":"integer","example":120}}}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Dívida não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/debtors":{"post":{"tags":["Devedores"],"summary":"Cria ou atualiza devedor (pelo CPF/CNPJ)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Debtor"}}}},"responses":{"200":{"description":"Devedor salvo","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"person_type":{"type":"string","enum":["pf","pj"]},"document_masked":{"type":"string"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/queries":{"post":{"tags":["Consultas"],"summary":"Consulta CPF/CNPJ (documento no corpo; debita créditos; estorna se falhar)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["document","product","purpose"],"properties":{"document":{"type":"string","description":"CPF ou CNPJ (com ou sem pontuação)"},"product":{"type":"string","enum":["consulta_basica","consulta_completa"]},"purpose":{"type":"string","enum":["concessao_credito","cobranca","cadastro"],"description":"Finalidade (LGPD)"}}}}}},"responses":{"201":{"description":"Consulta concluída","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Query"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Saldo insuficiente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Provedor fora do ar (provider_error); créditos estornados","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/queries/{id}":{"get":{"tags":["Consultas"],"summary":"Resultado salvo (acesso registrado na auditoria)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Consulta","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Query"}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wallet":{"get":{"tags":["Carteira"],"summary":"Saldo de créditos","responses":{"200":{"description":"Saldo","content":{"application/json":{"schema":{"type":"object","properties":{"balance_cents":{"type":"integer"}}}}}},"401":{"description":"Chave ausente, inválida ou revogada (invalid_api_key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Dados inválidos (validation_error) ou regra de negócio","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Limite de chamadas por minuto (rate_limited). Veja Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"debt.notice_sent":{"post":{"summary":"Aviso da régua enviado (canal e data)","parameters":[{"name":"Adimple-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762600000,v1=5f2b…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Recebido. Outro código → nova tentativa."}}}},"debt.negativated":{"post":{"summary":"Inclusão confirmada pelo birô (protocolo)","parameters":[{"name":"Adimple-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762600000,v1=5f2b…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Recebido. Outro código → nova tentativa."}}}},"debt.negativation_failed":{"post":{"summary":"Birô recusou; créditos estornados (error_code)","parameters":[{"name":"Adimple-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762600000,v1=5f2b…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Recebido. Outro código → nova tentativa."}}}},"debt.cleared":{"post":{"summary":"Baixa confirmada pelo birô (reason)","parameters":[{"name":"Adimple-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762600000,v1=5f2b…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Recebido. Outro código → nova tentativa."}}}},"debt.status_changed":{"post":{"summary":"Qualquer mudança de status da dívida (previous_status)","parameters":[{"name":"Adimple-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762600000,v1=5f2b…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Recebido. Outro código → nova tentativa."}}}},"payment.received":{"post":{"summary":"Pagamento registrado","parameters":[{"name":"Adimple-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762600000,v1=5f2b…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Recebido. Outro código → nova tentativa."}}}},"wallet.low_balance":{"post":{"summary":"Saldo abaixo de R$ 20,00","parameters":[{"name":"Adimple-Signature","in":"header","required":true,"schema":{"type":"string","example":"t=1762600000,v1=5f2b…"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Recebido. Outro código → nova tentativa."}}}}},"components":{"securitySchemes":{"chave":{"type":"http","scheme":"bearer","bearerFormat":"adm_live_…"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}},"Debtor":{"type":"object","required":["document","name"],"properties":{"document":{"type":"string"},"name":{"type":"string","minLength":3},"email":{"type":"string","format":"email"},"whatsapp":{"type":"string","example":"71999990000"},"address":{"type":"object","required":["zip_code"],"properties":{"zip_code":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","example":"BA"}}},"birth_date":{"type":"string","format":"date"},"mother_name":{"type":"string"}}},"NewDebt":{"type":"object","required":["debtor","title","nature","amount_cents","due_date"],"properties":{"debtor":{"$ref":"#/components/schemas/Debtor"},"title":{"type":"string","description":"Número do título/contrato"},"nature":{"type":"string","enum":["mensalidade","servicos","credito_direto_consumidor","cheque_devolvido","cartao_credito","credito_pessoal","credito_veiculo","credito_imobiliario","imobiliaria_administracao","locadora","consorcio","titulo_protestado","outros"]},"amount_cents":{"type":"integer","minimum":1},"due_date":{"type":"string","format":"date"},"installments":{"type":"integer","default":1},"debtor_role":{"type":"string","enum":["buyer","guarantor"],"default":"buyer"},"external_ref":{"type":"string","description":"Id da cobrança no seu sistema. Único por sistema: a mesma referência não entra duas vezes"},"start_dunning":{"type":"boolean","default":false}}},"NewPayment":{"type":"object","required":["amount_cents","paid_at","method"],"properties":{"amount_cents":{"type":"integer","minimum":1},"paid_at":{"type":"string","format":"date"},"method":{"type":"string","enum":["pix","cartao","dinheiro","boleto","informado_sistema"]}}},"Debt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_ref":{"type":["string","null"]},"origin":{"type":"string","enum":["painel","api","importacao"],"description":"Por onde a dívida entrou"},"system":{"type":["string","null"],"description":"Nome do sistema que enviou (o nome dado à chave de API)"},"title":{"type":"string"},"nature":{"type":"string"},"status":{"type":"string","enum":["rascunho","em_regua","aguardando_prazo","negativando","negativada","erro_negativacao","baixa_pendente","baixada","erro_baixa","paga","cancelada"]},"amount_cents":{"type":"integer"},"paid_cents":{"type":"integer"},"installments":{"type":"integer"},"due_date":{"type":"string","format":"date"},"debtor_role":{"type":"string","enum":["buyer","guarantor"]},"debtor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"person_type":{"type":"string","enum":["pf","pj"]},"document_masked":{"type":"string","example":"***.982.247-**"}}},"negativation":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["enviando","negativado","erro_envio","baixa_solicitada","baixado","erro_baixa"]},"bureau":{"type":"string"},"protocol":{"type":["string","null"]},"included_at":{"type":["string","null"],"format":"date-time"},"cleared_at":{"type":["string","null"],"format":"date-time"},"error_code":{"type":["string","null"]}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Query":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["processando","concluida","falhou"]},"product":{"type":"string"},"purpose":{"type":"string"},"document_masked":{"type":"string"},"traffic_light":{"type":["string","null"],"enum":["ok","atencao","restrito",null]},"score":{"type":["integer","null"]},"cost_cents":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"result":{"type":["object","null"],"description":"Dados retornados pelo provedor"}}},"WebhookEvent":{"type":"object","required":["id","type","created_at","data"],"properties":{"id":{"type":"string","format":"uuid","description":"Use para descartar repetições"},"type":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object"}}}}}}