{ "openapi": "3.1.0", "info": { "title": "bancosBR API", "version": "1.0.0", "description": "Bancos, agências e validação de domicílio bancário com os dados oficiais do Banco Central, atualizados todo dia. Um serviço Minesoft.\n\nA validação confere existência e formato; **não** confirma a titularidade da conta.", "contact": { "name": "Minesoft", "url": "https://bancosbr.minesoft.com.br" } }, "servers": [ { "url": "https://bancosbr.minesoft.com.br/api/public/v1" } ], "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "example": { "error": { "code": "chave_invalida", "message": "Chave inválida ou revogada." } } }, "Institution": { "type": "object", "properties": { "ispb": { "type": "string" }, "compe_code": { "type": [ "string", "null" ] }, "short_name": { "type": "string" }, "full_name": { "type": "string" }, "cnpj": { "type": [ "string", "null" ] }, "institution_type": { "type": [ "string", "null" ] }, "in_str": { "type": "boolean" }, "in_pix": { "type": "boolean" }, "pix_modality": { "type": [ "string", "null" ] }, "has_branches": { "type": "boolean" }, "active": { "type": "boolean" }, "inactivated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "example": { "ispb": "18236120", "compe_code": "260", "short_name": "NU PAGAMENTOS - IP", "has_branches": false, "active": true } }, "Branch": { "type": "object", "properties": { "ispb": { "type": "string" }, "cnpj_seq": { "type": "string" }, "number": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "district": { "type": "string" }, "zip": { "type": "string" }, "city": { "type": "string" }, "uf": { "type": "string" }, "phone": { "type": "string" }, "active": { "type": "boolean" } }, "example": { "ispb": "60701190", "number": "3858", "name": "SAO JOSE DOS PINHAIS - PR", "city": "SAO JOSE DOS PINHAIS", "uf": "PR", "active": true } }, "ValidateRequest": { "type": "object", "required": [ "bank", "agency", "account", "account_dv", "account_type" ], "properties": { "bank": { "type": "string", "description": "ISPB ou COMPE" }, "agency": { "type": "string", "maxLength": 5 }, "agency_dv": { "type": "string", "maxLength": 1 }, "account": { "type": "string", "maxLength": 20 }, "account_dv": { "type": "string", "maxLength": 1 }, "account_type": { "type": "string", "enum": [ "corrente", "poupanca" ] } }, "example": { "bank": "341", "agency": "3858", "account": "12345", "account_dv": "6", "account_type": "corrente" } }, "ValidateResponse": { "type": "object", "properties": { "valid": { "type": "boolean" }, "checks": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "ok", "invalido", "nao_verificado", "sem_lista" ] } }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "formato_invalido", "banco_inexistente", "banco_inativo", "banco_ambiguo", "agencia_inexistente", "agencia_inativa", "dv_agencia_invalido", "dv_conta_invalido", "tipo_invalido" ] }, "field": { "type": "string" }, "message": { "type": "string" } } } }, "bank": { "type": [ "object", "null" ] }, "branch": { "type": [ "object", "null" ] }, "agency_check": { "type": "string" }, "suggested_agency": { "type": "string" }, "data_version": { "type": "object" } }, "example": { "valid": false, "checks": { "format": "ok", "bank": "ok", "agency": "ok", "agency_dv": "nao_verificado", "account_dv": "invalido", "account_type": "ok" }, "reasons": [ { "code": "dv_conta_invalido", "field": "account_dv", "message": "Dígito da conta não confere para ITAÚ UNIBANCO S.A.." } ], "bank": { "ispb": "60701190", "compe_code": "341", "short_name": "ITAÚ UNIBANCO S.A." }, "branch": { "number": "3858", "name": "SAO JOSE DOS PINHAIS - PR", "city": "SAO JOSE DOS PINHAIS", "uf": "PR" }, "data_version": { "str": "2026-11-12", "pix": "2026-11-12", "olinda": "2026-11-12" } } }, "WebhookPayload": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "banks.changed", "branches.changed" ] }, "from_seq": { "type": "integer" }, "to_seq": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "seq": { "type": "integer" }, "op": { "type": "string", "enum": [ "insert", "update", "inactivate", "reactivate" ] }, "key": { "type": "string" }, "changed_fields": { "type": [ "array", "null" ], "items": { "type": "string" } }, "record": { "type": "object" } } } } } } } }, "x-reason-codes": { "formato_invalido": "Campo ausente ou com formato inválido.", "banco_inexistente": "Banco não encontrado.", "banco_inativo": "Banco existe, mas está inativo.", "banco_ambiguo": "O código COMPE aponta para mais de uma instituição.", "agencia_inexistente": "Agência não encontrada para este banco.", "agencia_inativa": "Agência existe, mas está inativa.", "dv_agencia_invalido": "Dígito da agência não confere.", "dv_conta_invalido": "Dígito da conta não confere.", "tipo_invalido": "Tipo de conta deve ser corrente ou poupanca." }, "paths": { "/banks": { "get": { "security": [ { "ApiKey": [] } ], "summary": "Buscar bancos", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "compe", "in": "query", "schema": { "type": "string" } }, { "name": "ispb", "in": "query", "schema": { "type": "string" } }, { "name": "has_branches", "in": "query", "schema": { "type": "string" } }, { "name": "include_inactive", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Institution" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/banks/{bank}": { "get": { "security": [ { "ApiKey": [] } ], "summary": "Detalhe do banco", "parameters": [ { "name": "bank", "in": "path", "required": true, "description": "ISPB (8 dígitos) ou COMPE (3 dígitos)", "schema": { "type": "string" }, "example": "341" } ], "responses": { "200": { "description": "Banco", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Institution" } } } } } }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Banco não encontrado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "COMPE ambíguo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/banks/{bank}/branches": { "get": { "security": [ { "ApiKey": [] } ], "summary": "Buscar agências do banco", "description": "q busca no número (sem zeros à esquerda), no nome e na cidade, sem diferenciar acento.", "parameters": [ { "name": "bank", "in": "path", "required": true, "description": "ISPB (8 dígitos) ou COMPE (3 dígitos)", "schema": { "type": "string" }, "example": "341" }, { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "city", "in": "query", "schema": { "type": "string" } }, { "name": "uf", "in": "query", "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } }, "next_cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/banks/{bank}/branches/{number}": { "get": { "security": [ { "ApiKey": [] } ], "summary": "Detalhe da agência", "parameters": [ { "name": "bank", "in": "path", "required": true, "description": "ISPB (8 dígitos) ou COMPE (3 dígitos)", "schema": { "type": "string" }, "example": "341" }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string" }, "example": "3858" } ], "responses": { "200": { "description": "Agência", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Branch" } } } } } }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Agência não encontrada", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/validate": { "post": { "security": [ { "ApiKey": [] } ], "summary": "Validar domicílio bancário", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" } } } }, "responses": { "200": { "description": "Resultado", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } }, "400": { "description": "JSON inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/validate/batch": { "post": { "security": [ { "ApiKey": [] } ], "summary": "Validar em lote (até 500)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/ValidateRequest" } } } } } } }, "responses": { "200": { "description": "Resultado por posição" }, "400": { "description": "Lote inválido", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/export/snapshot": { "get": { "security": [ { "ApiKey": [] } ], "summary": "Base completa paginada", "parameters": [ { "name": "entity", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "institution", "branch" ] } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Página com seq atual do change_log" }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/export/changes": { "get": { "security": [ { "ApiKey": [] } ], "summary": "Mudanças desde um cursor", "parameters": [ { "name": "since_seq", "in": "query", "required": true, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Itens com o registro atual" }, "401": { "description": "Chave ausente, inválida ou revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Limite excedido. Veja Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/status": { "get": { "summary": "Situação das fontes (sem chave)", "responses": { "200": { "description": "Última carga de cada fonte" } } } }, "/openapi.json": { "get": { "summary": "Esta especificação (sem chave)", "responses": { "200": { "description": "OpenAPI 3.1" } } } } }, "webhooks": { "banks.changed": { "post": { "summary": "Mudanças em bancos", "description": "Assinado em X-BancosBR-Signature: t=,v1=HMAC-SHA256(segredo, t + '.' + corpo).", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Recebido" } } } }, "branches.changed": { "post": { "summary": "Mudanças em agências", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Recebido" } } } } } }