{
  "openapi": "3.0.3",
  "info": {
    "title": "Blue Credit API",
    "description": "API REST para consultas cadastrais, veiculares, protestos, score, dívidas e outras fontes. O catálogo de integrações é público; a execução de consultas usa o header HTTP-API-KEY e pode debitar saldo pré-pago.",
    "version": "19.0.1.0.0",
    "contact": {
      "name": "Conexão Azul - Suporte Blue Credit",
      "email": "ola@conexaoazul.com",
      "url": "https://www.conexaoazul.com"
    },
    "license": {
      "name": "Proprietary"
    },
    "x-last-verified": "2026-07-22"
  },
  "servers": [
    {
      "url": "https://api.conexaoazul.com/api/v1",
      "description": "Produção"
    }
  ],
  "paths": {
    "/credit/integrations": {
      "get": {
        "summary": "Listar integrações disponíveis",
        "description": "Endpoint público e gratuito. Retorna as integrações ativas, tipos de documento e preços atuais.",
        "operationId": "listCreditIntegrations",
        "tags": [
          "Integrações"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Catálogo de integrações",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Integration"
                  }
                },
                "example": [
                  {
                    "code": "cnpj_completo",
                    "name": "CNPJ Completo",
                    "category": "cadastral",
                    "document_type": "cnpj",
                    "document_param_name": "cnpj",
                    "price_nivel_1": 0.105,
                    "price_nivel_2": 0.06
                  },
                  {
                    "code": "cpf_simples",
                    "name": "CPF Simples",
                    "category": "cadastral",
                    "document_type": "cpf",
                    "document_param_name": "cpf",
                    "price_nivel_1": 0.165,
                    "price_nivel_2": 0.09
                  }
                ]
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/credit/query": {
      "post": {
        "summary": "Executar consulta",
        "description": "Executa a integração informada. A chamada usa a configuração de preço e o saldo associados à chave.",
        "operationId": "executeCreditQuery",
        "tags": [
          "Consultas"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QueryRequest"
              },
              "examples": {
                "cnpj": {
                  "summary": "CNPJ Completo",
                  "value": {
                    "integration_code": "cnpj_completo",
                    "document": "11222333000181"
                  }
                },
                "cpf": {
                  "summary": "CPF Simples",
                  "value": {
                    "integration_code": "cpf_simples",
                    "document": "00000000191"
                  }
                },
                "placa": {
                  "summary": "FIPE por placa",
                  "value": {
                    "integration_code": "fipe",
                    "document": "ABC1D23"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Consulta processada. Verifique o campo status no corpo.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueryResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Provider retornou sucesso",
                    "value": {
                      "status": "success",
                      "data": {
                        "status": "sucesso",
                        "dados": {
                          "documento": "11222333000181"
                        }
                      },
                      "aux": [],
                      "error": null,
                      "cost": 0.105
                    }
                  },
                  "provider_error": {
                    "summary": "Consulta executada sem resultado no provider",
                    "value": {
                      "status": "error",
                      "data": null,
                      "aux": [],
                      "error": "Documento não encontrado na fonte consultada",
                      "cost": 0.105
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientBalance"
          },
          "404": {
            "$ref": "#/components/responses/IntegrationNotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "HTTP-API-KEY",
        "description": "Chave confidencial associada à conta. Envie somente no endpoint de consulta e nunca exponha no frontend."
      }
    },
    "schemas": {
      "Integration": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code",
          "name",
          "category",
          "document_type",
          "document_param_name",
          "price_nivel_1",
          "price_nivel_2"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Código enviado em integration_code.",
            "example": "cnpj_completo"
          },
          "name": {
            "type": "string",
            "description": "Nome legível da integração.",
            "example": "CNPJ Completo"
          },
          "category": {
            "type": "string",
            "description": "Categoria funcional.",
            "example": "cadastral"
          },
          "document_type": {
            "type": "string",
            "description": "Tipo de documento aceito pela integração.",
            "example": "cnpj"
          },
          "document_param_name": {
            "type": "string",
            "description": "Nome semântico do documento; o endpoint unificado recebe o valor em document.",
            "example": "cnpj"
          },
          "price_nivel_1": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "description": "Preço padrão em reais.",
            "example": 0.105
          },
          "price_nivel_2": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "description": "Preço para contas habilitadas no nível 2, conforme configuração comercial.",
            "example": 0.06
          }
        }
      },
      "QueryRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "integration_code",
          "document"
        ],
        "properties": {
          "integration_code": {
            "type": "string",
            "minLength": 1,
            "description": "Código obtido no catálogo público.",
            "example": "cnpj_completo"
          },
          "document": {
            "type": "string",
            "minLength": 1,
            "description": "CPF, CNPJ, placa, nome ou outro identificador aceito pela integração.",
            "example": "11222333000181"
          }
        }
      },
      "QueryResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "status",
          "data",
          "aux",
          "error",
          "cost"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success",
              "error"
            ],
            "description": "Resultado da consulta ao provider."
          },
          "data": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "Payload específico da integração."
          },
          "aux": {
            "type": "array",
            "items": {},
            "description": "Dados auxiliares, quando disponíveis."
          },
          "error": {
            "type": "string",
            "nullable": true,
            "description": "Mensagem do provider quando status é error."
          },
          "cost": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "description": "Valor debitado em reais."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "string"
          }
        }
      },
      "ValidationIssue": {
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "properties": {
          "loc": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            }
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        }
      },
      "ValidationErrorResponse": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ValidationIssue"
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Chave ausente ou inválida.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "detail": "Not authenticated"
            }
          }
        }
      },
      "InsufficientBalance": {
        "description": "Saldo insuficiente.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "detail": "Saldo insuficiente"
            }
          }
        }
      },
      "IntegrationNotFound": {
        "description": "Código de integração não encontrado.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "detail": "Integração não encontrada"
            }
          }
        }
      },
      "ValidationError": {
        "description": "Payload inválido.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationErrorResponse"
            },
            "example": {
              "detail": [
                {
                  "loc": [
                    "body",
                    "document"
                  ],
                  "msg": "field required",
                  "type": "value_error.missing"
                }
              ]
            }
          }
        }
      },
      "InternalError": {
        "description": "Erro interno ou falha transitória.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "detail": "Internal server error"
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Integrações",
      "description": "Catálogo público de integrações e preços."
    },
    {
      "name": "Consultas",
      "description": "Execução autenticada de consultas."
    }
  ]
}