{
    "openapi": "3.0.3",
    "info": {
        "title": "Consult API v3 - Negativacao",
        "version": "3.0.0",
        "description": "Inclusao, consulta e baixa de negativacoes (Pefin). Substitui a API de negativacao da extranet (`/api_negativacao/*`), que continua no ar durante a migracao.\n\n**Autenticacao**: o mesmo token da extranet, no header `APITOKEN`. Quem ja integrava so troca a URL e o formato.\n\n**O que mudou em relacao a extranet**\n\n- Sucesso e erro vem pelo status HTTP; some o campo `success` e o array externo de um elemento.\n- Erro tem sempre a forma `{\"erro\": {\"codigo\", \"mensagem\", \"detalhes\"}}`.\n- Campos em snake_case pt-BR: `natureza_id`, `documento`, `logradouro`, `cidade`, `data_vencimento`, `valor`...\n- Data em `AAAA-MM-DD` e valor numerico com ponto decimal (`1234.56`), nao mais `dd/mm/aaaa` e `1.234,56`.\n- `tipo_pessoa` e `fisica` ou `juridica`.\n- O documento e validado (digito verificador) antes de gravar.\n- Campo maior que o limite da coluna e rejeitado em vez de cortado.\n- A listagem e paginada (`pagina`, `limite`).\n- A baixa passa a gravar o motivo informado e confere que ele existe.\n- `numero` e campo proprio, mas e gravado junto do logradouro (ate 45 caracteres no total).\n\n**Status da negativacao** (campo `status`, com `id` e `nome`)\n\n| id | nome | significado |\n|---|---|---|\n| 22 | Aguardando Processamento | recebida, ainda nao enviada ao Serasa |\n| 26 | Processando | enviada ao Serasa, aguardando o retorno |\n| 25 | Incluido | inclusao confirmada pelo Serasa |\n| 87 | Codigo BL07 | retida para conferencia interna; liberada, passa para 22 |\n| 23 | Erro | recusada pelo Serasa por erro nos dados |\n| 86 | Nao Autorizado | recusada pelo Serasa por falta de autorizacao |\n| 63 | Decursado | recusada pelo Serasa: prazo para negativar a divida vencido |\n| 91 | Suspensao | recusada pelo Serasa por suspensao |\n| 33 | Aguardando Baixa | baixa enviada ao Serasa, aguardando confirmacao |\n| 24 | Baixado | baixa confirmada (ou pedida antes do envio ao Serasa) |\n\n**Limite mensal**: ao atingir o limite mensal de negativacoes da conta, a inclusao e recusada com `429 limite_negativacoes_excedido` e `detalhes.limite_mensal`. Nada e incluido alem do limite.\n\n**Acompanhamento**: nao ha webhook. O status e acompanhado por `GET /v3/negativacoes/{id}` ou pela listagem."
    },
    "servers": [
        {
            "url": "https://api.consultcenter.com.br"
        }
    ],
    "tags": [
        {
            "name": "negativacao",
            "description": "Inclusao, consulta e baixa de negativacoes (Pefin) no Serasa."
        },
        {
            "name": "catalogo",
            "description": "Valores aceitos nos campos `natureza_id` e `motivo_baixa_id`."
        }
    ],
    "security": [
        {
            "ApiToken": []
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiToken": {
                "type": "apiKey",
                "in": "header",
                "name": "APITOKEN"
            }
        },
        "schemas": {
            "Natureza": {
                "type": "object",
                "required": [
                    "id",
                    "nome"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "nome": {
                        "type": "string"
                    }
                }
            },
            "MotivoBaixa": {
                "type": "object",
                "required": [
                    "id",
                    "descricao"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "descricao": {
                        "type": "string"
                    }
                }
            },
            "NegativacaoNova": {
                "type": "object",
                "required": [
                    "natureza_id",
                    "tipo_pessoa",
                    "documento",
                    "nome",
                    "cep",
                    "logradouro",
                    "numero",
                    "bairro",
                    "cidade",
                    "uf",
                    "data_vencimento",
                    "data_termino",
                    "valor"
                ],
                "description": "Para natureza `118` (cheque) tambem sao obrigatorios `banco`, `agencia`, `numero_cheque` e `codigo_alinea` (12, 13 ou 14), e `numero_contrato` e `nosso_numero` deixam de ser. Nas demais, `numero_contrato` e `nosso_numero` sao obrigatorios.",
                "properties": {
                    "natureza_id": {
                        "type": "integer",
                        "description": "id de GET /v3/negativacoes/naturezas"
                    },
                    "tipo_pessoa": {
                        "type": "string",
                        "enum": [
                            "fisica",
                            "juridica"
                        ]
                    },
                    "documento": {
                        "type": "string",
                        "description": "CPF ou CNPJ (inclusive alfanumerico) do devedor, com ou sem mascara; precisa bater com tipo_pessoa"
                    },
                    "nome": {
                        "type": "string",
                        "maxLength": 70
                    },
                    "cep": {
                        "type": "string",
                        "description": "8 digitos, com ou sem hifen"
                    },
                    "logradouro": {
                        "type": "string"
                    },
                    "numero": {
                        "type": "string",
                        "description": "junto do logradouro, no maximo 45 caracteres"
                    },
                    "complemento": {
                        "type": "string",
                        "maxLength": 45,
                        "nullable": true
                    },
                    "bairro": {
                        "type": "string",
                        "maxLength": 20
                    },
                    "cidade": {
                        "type": "string",
                        "maxLength": 25
                    },
                    "uf": {
                        "type": "string",
                        "minLength": 2,
                        "maxLength": 2
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 145,
                        "nullable": true
                    },
                    "email2": {
                        "type": "string",
                        "format": "email",
                        "maxLength": 145,
                        "nullable": true
                    },
                    "telefone": {
                        "type": "string",
                        "description": "DDD + numero",
                        "nullable": true
                    },
                    "celular": {
                        "type": "string",
                        "description": "DDD + numero",
                        "nullable": true
                    },
                    "celular2": {
                        "type": "string",
                        "description": "DDD + numero",
                        "nullable": true
                    },
                    "banco": {
                        "type": "string",
                        "maxLength": 4,
                        "description": "so cheque"
                    },
                    "agencia": {
                        "type": "string",
                        "maxLength": 4,
                        "description": "so cheque"
                    },
                    "numero_cheque": {
                        "type": "string",
                        "maxLength": 6,
                        "description": "so cheque"
                    },
                    "codigo_alinea": {
                        "type": "integer",
                        "enum": [
                            12,
                            13,
                            14
                        ],
                        "description": "so cheque"
                    },
                    "data_vencimento": {
                        "type": "string",
                        "format": "date"
                    },
                    "data_termino": {
                        "type": "string",
                        "format": "date"
                    },
                    "data_nascimento": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "nosso_numero": {
                        "type": "string",
                        "maxLength": 9,
                        "description": "so digitos"
                    },
                    "numero_contrato": {
                        "type": "string",
                        "maxLength": 16
                    },
                    "valor": {
                        "type": "number",
                        "format": "double",
                        "minimum": 3,
                        "description": "em reais, ponto decimal, ate 2 casas"
                    }
                }
            },
            "Negativacao": {
                "type": "object",
                "required": [
                    "id",
                    "status",
                    "natureza",
                    "tipo_pessoa",
                    "documento",
                    "nome",
                    "valor"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "status": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "nome": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "natureza": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "nome": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "tipo_pessoa": {
                        "type": "string",
                        "enum": [
                            "fisica",
                            "juridica"
                        ]
                    },
                    "documento": {
                        "type": "string",
                        "description": "sem mascara"
                    },
                    "nome": {
                        "type": "string",
                        "nullable": true
                    },
                    "endereco": {
                        "type": "object",
                        "properties": {
                            "cep": {
                                "type": "string",
                                "nullable": true
                            },
                            "logradouro": {
                                "type": "string",
                                "nullable": true
                            },
                            "complemento": {
                                "type": "string",
                                "nullable": true
                            },
                            "bairro": {
                                "type": "string",
                                "nullable": true
                            },
                            "cidade": {
                                "type": "string",
                                "nullable": true
                            },
                            "estado": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "contato": {
                        "type": "object",
                        "properties": {
                            "email": {
                                "type": "string",
                                "nullable": true
                            },
                            "email2": {
                                "type": "string",
                                "nullable": true
                            },
                            "telefone": {
                                "type": "string",
                                "nullable": true
                            },
                            "celular": {
                                "type": "string",
                                "nullable": true
                            },
                            "celular2": {
                                "type": "string",
                                "nullable": true
                            }
                        }
                    },
                    "cheque": {
                        "type": "object",
                        "nullable": true,
                        "description": "so na natureza 118",
                        "properties": {
                            "banco": {
                                "type": "string",
                                "nullable": true
                            },
                            "agencia": {
                                "type": "string",
                                "nullable": true
                            },
                            "numero_cheque": {
                                "type": "string",
                                "nullable": true
                            },
                            "codigo_alinea": {
                                "type": "integer",
                                "nullable": true
                            }
                        }
                    },
                    "data_vencimento": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "data_termino": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "data_nascimento": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                    },
                    "nosso_numero": {
                        "type": "string",
                        "nullable": true
                    },
                    "numero_contrato": {
                        "type": "string",
                        "nullable": true
                    },
                    "valor": {
                        "type": "number",
                        "format": "double"
                    },
                    "origem_baixa": {
                        "type": "string",
                        "nullable": true
                    },
                    "criado_em": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    }
                }
            },
            "Erro": {
                "type": "object",
                "required": [
                    "erro"
                ],
                "properties": {
                    "erro": {
                        "type": "object",
                        "required": [
                            "codigo",
                            "mensagem"
                        ],
                        "properties": {
                            "codigo": {
                                "type": "string",
                                "enum": [
                                    "validacao_falhou",
                                    "negativacao_nao_encontrada",
                                    "negativacao_duplicada",
                                    "negativacao_nao_baixavel",
                                    "limite_negativacoes_excedido",
                                    "parametro_ausente",
                                    "parametro_invalido",
                                    "nao_autenticado",
                                    "produto_sem_acesso"
                                ]
                            },
                            "mensagem": {
                                "type": "string"
                            },
                            "detalhes": {
                                "type": "object",
                                "additionalProperties": true,
                                "description": "Em `validacao_falhou`: `erros`, lista de `{campo, mensagem}`."
                            }
                        }
                    }
                }
            }
        }
    },
    "paths": {
        "/v3/negativacoes/naturezas": {
            "get": {
                "summary": "Lista as naturezas de operacao",
                "description": "Use o `id` em `natureza_id` ao incluir. A natureza `118` e cheque e muda os campos obrigatorios.",
                "operationId": "listar_naturezas",
                "tags": [
                    "catalogo"
                ],
                "responses": {
                    "200": {
                        "description": "Naturezas ativas",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "total",
                                        "itens"
                                    ],
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "itens": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Natureza"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "nao_autenticado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "produto_sem_acesso",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v3/negativacoes/motivos-baixa": {
            "get": {
                "summary": "Lista os motivos de baixa",
                "description": "Use o `id` em `motivo_baixa_id` ao baixar.",
                "operationId": "listar_motivos_baixa",
                "tags": [
                    "catalogo"
                ],
                "responses": {
                    "200": {
                        "description": "Motivos de baixa",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "total",
                                        "itens"
                                    ],
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "itens": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/MotivoBaixa"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "nao_autenticado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "produto_sem_acesso",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v3/negativacoes": {
            "get": {
                "summary": "Lista as negativacoes do cliente",
                "description": "Mais recentes primeiro. Sem filtro, devolve a primeira pagina.",
                "operationId": "listar_negativacoes",
                "tags": [
                    "negativacao"
                ],
                "parameters": [
                    {
                        "name": "documento",
                        "in": "query",
                        "required": false,
                        "description": "CPF ou CNPJ do devedor, com ou sem mascara",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "pagina",
                        "in": "query",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "default": 1
                        }
                    },
                    {
                        "name": "limite",
                        "in": "query",
                        "required": false,
                        "description": "itens por pagina",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 500,
                            "default": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Pagina de negativacoes. `total` e o numero de registros que casam com o filtro, nao o da pagina.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "required": [
                                        "total",
                                        "pagina",
                                        "limite",
                                        "itens"
                                    ],
                                    "properties": {
                                        "total": {
                                            "type": "integer"
                                        },
                                        "pagina": {
                                            "type": "integer"
                                        },
                                        "limite": {
                                            "type": "integer"
                                        },
                                        "itens": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Negativacao"
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "parametro_invalido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "nao_autenticado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "produto_sem_acesso",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "summary": "Inclui uma negativacao",
                "description": "Grava a negativacao como `Aguardando Processamento` (status 22); ela segue na proxima remessa ao Serasa. Dependendo das regras de prevencao (valor alto, documento em lista de bloqueio, UF nao autorizada...), o registro fica retido para conferencia interna e `status` volta com outro codigo - a inclusao continua sendo 201.\n\nO devedor e avisado por e-mail e SMS quando o cadastro do cliente estiver configurado para isso. Falha nesse envio nao desfaz a inclusao.\n\nEnviar a mesma inclusao duas vezes em menos de 3 segundos devolve 409 `negativacao_duplicada`. Contrato que ja consta como incluido para o mesmo documento ganha sufixo (`123` vira `123A`).",
                "operationId": "incluir_negativacao",
                "tags": [
                    "negativacao"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/NegativacaoNova"
                            },
                            "example": {
                                "natureza_id": 120,
                                "tipo_pessoa": "fisica",
                                "documento": "52998224725",
                                "nome": "MARIA DEMONSTRACAO",
                                "cep": "01310100",
                                "logradouro": "AVENIDA PAULISTA",
                                "numero": "1000",
                                "complemento": "SALA 12",
                                "bairro": "BELA VISTA",
                                "cidade": "SAO PAULO",
                                "uf": "SP",
                                "email": "maria@exemplo.com.br",
                                "celular": "11908331155",
                                "data_vencimento": "2026-03-10",
                                "data_termino": "2026-03-10",
                                "nosso_numero": "123456",
                                "numero_contrato": "CT-2026-001",
                                "valor": 1234.56
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Negativacao incluida",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Negativacao"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "validacao_falhou",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "negativacao_duplicada",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "limite_negativacoes_excedido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "parametro_invalido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "nao_autenticado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "produto_sem_acesso",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v3/negativacoes/{id}": {
            "get": {
                "summary": "Consulta uma negativacao",
                "operationId": "exibir_negativacao",
                "tags": [
                    "negativacao"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "id devolvido na inclusao",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "A negativacao",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Negativacao"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "negativacao_nao_encontrada",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "nao_autenticado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "produto_sem_acesso",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/v3/negativacoes/{id}/baixa": {
            "post": {
                "summary": "Baixa uma negativacao",
                "description": "Pendente (22) e baixada na hora (24). Incluida no Serasa (25) vira `Aguardando Baixa` (33) e sai na proxima remessa. Qualquer outro status devolve 409 `negativacao_nao_baixavel`.",
                "operationId": "baixar_negativacao",
                "tags": [
                    "negativacao"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "id devolvido na inclusao",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "motivo_baixa_id"
                                ],
                                "properties": {
                                    "motivo_baixa_id": {
                                        "type": "integer",
                                        "description": "id de GET /v3/negativacoes/motivos-baixa"
                                    }
                                }
                            },
                            "example": {
                                "motivo_baixa_id": 1
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "A negativacao, ja com o novo status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Negativacao"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "negativacao_nao_encontrada",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "negativacao_nao_baixavel",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "parametro_ausente, parametro_invalido",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "nao_autenticado",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "produto_sem_acesso",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Erro"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}