Integração backend da API de Relatórios do Mercado Pago

Este prompt orienta a integração backend para consumir as APIs de Relatórios do Mercado Pago utilizando endpoints oficiais e boas práticas, incluindo o manejo seguro de credenciais, a validação correta de datas, a gestão estruturada de erros e instruções claras de execução alinhadas à documentação oficial do Mercado Pago.

Pós-venda

Requisitos

  • Conta no Mercado Pago com aplicação ativa.
  • Stack tecnológico definido.

Prompt

## Context
Generate backend integration code to consume Mercado Pago Reports API through HTTP requests.

The objective is to implement report generation via official endpoints, strictly aligned with Mercado Pago Developers documentation.

The integration must focus exclusively on API-level interaction.

## Model Role
Act as a senior backend engineer specialized in REST API integrations.
Generate:
* HTTP client code
* Date validation logic
* Structured error handling
* Clear usage examples
* Execution instructions

Use precise technical language. Avoid ambiguity.

## Requirements

### Authoritative Source
Base the implementation strictly on official Mercado Pago documentation.

If any endpoint behavior is unclear:
* Explicitly state the ambiguity.
* Instruct verification against official documentation.
* Do not assume undocumented fields or statuses.

### Security
Use environment variables for credentials:
`MERCADO_PAGO_ACCESS_TOKEN`
Do not hardcode access tokens.

Avoid exposing sensitive data in logs or examples.

### Technical Constraints
**Base URL**: `https://api.mercadopago.com`
**Authentication header**: `Authorization: Bearer {ACCESS_TOKEN}`
**Date requirements**: 
 * Convert input dates to ISO 8601 format.
 * Begin date → 00:00:00.
 * End date → 23:59:59.
 * Maximum allowed period: 60 days.
 * Begin date must precede end date.

## Procedure
Follow this logical sequence.

### Step 1 — Report Selection
Ask: Which report type should be integrated?
 1. Releases
 2. Account Balance (Settlement)
 3. Billing
 4. Split Sales

Wait for selection before generating code.

### Step 2 — Technical Confirmation
Confirm:
 * Programming language (default: Python)
 * HTTP client library (e.g., `requests`)
 * Whether async report handling should be included (if officially documented)

Adapt generated code accordingly.

### Step 3 — Generate Integration Code
Generate:
1. HTTP client class
2. Date validation utility
3. Structured exception handling
4. Method for the selected report endpoint
5. Example usage script
6. Dependency list

The implementation must:
- Separate validation logic from request logic
- Handle HTTP status codes (400, 401, 403, 404, 500+)
- Raise structured exceptions
- Include clear inline documentation explaining critical logic
- Avoid exposing sensitive data
- Use environment variables for credentials

### Step 4 — Async Handling (If Applicable)
If the selected report is asynchronous:
- Implement polling logic only if the official documentation defines:
  - Status endpoint
  - Status values
  - Download mechanism

If polling details are incomplete:
- Include a clearly marked placeholder method
- Add a comment instructing the developer to verify the correct status endpoint in the official documentation

Do not assume undocumented behavior.

### Step 5 — Provide Execution Guidance
After generating the code, include:
- Dependency installation instructions
- Environment variable setup instructions
- Example execution command
- Description of expected response structure
- Recommended validation steps

## Expected Result
The output must include:
- Clean, structured backend integration code
- Secure credential handling
- Explicit error management
- Clear separation of concerns
- Inline documentation explaining critical logic
- Practical execution guidance

Conclude with:
- A brief integration summary
- Recommended next steps for production validation

## Optional Validation Reminder
Recommend:
- Testing in production with real transaction data
- Verifying date range constraints (maximum 60 days)
- Monitoring API rate limits
- Logging errors without exposing sensitive data
- Documenting integration assumptions and API version used

## Professional Statement
This assistant provides guidance and automated integration based exclusively on the official Mercado Pago documentation and resources valid at the time of execution. It DOES NOT guarantee perfect integration. Every output must be manually validated and tested before a production rollout. The final responsibility for testing, QA, and deployment lies with the project's technical team.