Skip to main content
Version: 1.0.0

banca.me Partners API

The banca.me Partners API provides endpoints for creating and managing PartnerEntities. This API is designed for Partners who want to manage their partner entities in order to have a level of isolation for leads evaluated through Risk Policies for each PartnerEntity in order to satisfy their private B2B customers. Moreover this model reflects Merchants (bnpl), Projects (Real State) and Real State (Real State Brokers).

Features​

This usage provides a Partner the capabilities of managing their own B2B customer relationships by:

  • Enabling them to interact with the platform (make their own evaluations or purchases) using their own id (referenced to banca.me as externalEntityId). Reference POST endpoint.
  • Getting all of the PartnerEntities a Partner has created. Reference GET endpoint.
  • Updating a PartnerEntity values in order to update the name o if the PartnerEntity is no longer active. Reference PATCH endpoint.

The API also exposes read endpoints over your own leads and their evaluations: look an evaluation up by lead id or by RUT, page through your leads, read a lead's contact details, and get a download link for the evaluation report. These reads never write and never call a third party.

Pushing rather than polling? The same evaluations are delivered as the pre_approve webhook event — see the event catalog.

Reads are scoped to your own leads​

Every read endpoint is bounded to the leads that belong to you.

On the lead and evaluation reads — by lead id, by RUT, the lead list and the lead detail — a lead that does not exist, one that belongs to another partner, and one that is out of scope all return the same 404 with the same body, so those endpoints cannot be used to enumerate leads you do not hold.

The report endpoint does not collapse its errors this way: an unknown preApproveId returns 404, while a pre-approval that belongs to another partner returns 401. Treat both as "not available to you" rather than inferring anything from the difference.

The lead read endpoints require the evaluation module; a partner without it is rejected with a 403 naming the module.

Base URL​

The base URL for all API requests is:

https://api.banca.me

Rate Limiting​

The API implements rate limiting to ensure fair usage:

  • 2 requests per second, measured over a one-second window. It is a burst limit, not a per-minute quota: three calls inside the same second return 429 even if the minute is nearly idle. Space out bulk operations rather than batching them.
  • 429 status code is returned when limits are exceeded

Error Handling​

The API uses standard HTTP status codes and provides detailed error messages in the response body. Common error codes include:

  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 429: Too Many Requests
  • 500: Internal Server Error

Data Formats​

The API accepts and returns data in the following formats:

  • Request: application/json
  • Response: application/json

Best Practices​

  1. Entity Management
  • Create entities with meaningful names
  • Keep track of external IDs
  • Update entity information when needed
  • Monitor entity status
  1. Error Handling
  • Implement proper error handling
  • Check HTTP status codes
  • Parse error messages from responses
  • Implement retry logic for temporary failures
  1. Security
  • Keep your API token secure
  • Never expose tokens in client-side code
  • Validate all input data
  • Use HTTPS for all requests
  1. Performance
  • Cache entity information when appropriate
  • Monitor rate limits
  • Implement proper error recovery
  • Optimize API calls

Authentication​

Partner access token provided by banca.me

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer