Homologation criteria

Prepare your Merchant API integration for production.

Requirements:

Application fully ready for testing
Professional account (CNPJ) — Personal/Student accounts (CPF) not accepted
Valid access token provided during onboarding

Endpoint checklist

Validate that each endpoint works correctly:

Endpoint	Method	Approval criteria
`/merchants`	`GET`	Returns array of stores with `id`, `name`, `corporateName`
`/merchants/{merchantId}`	`GET`	Returns object with operations and complete address
`/merchants/{merchantId}/status`	`GET`	Returns `state` (OK/WARNING/CLOSED/ERROR) with validations
`/merchants/{merchantId}/interruptions`	`GET`	Returns empty array or active interruptions
`/merchants/{merchantId}/interruptions`	`POST`	Creates pause with `id`, `start`, `end` and returns `201`
`/merchants/{merchantId}/interruptions/{id}`	`DELETE`	Removes pause and returns `204` with no content
`/merchants/{merchantId}/opening-hours`	`GET`	Returns array of shifts with `dayOfWeek`, `start`, `duration`
`/merchants/{merchantId}/opening-hours`	`PUT`	Updates hours and returns `201` with created shifts

Test scenarios

Authentication

Test: Request without token Expected: 401 Unauthorized with clear message Pass: Error returned with code 401Test: Invalid token Expected: 401 Unauthorized Pass: Error returned with code 401Test: Valid token Expected: 200 with store data Pass: Successful response

List stores

Test: GET /merchants without parameters Expected: Array with all stores Pass: Minimum 1 store returned with valid idTest: GET /merchants?page=1&size=10 Expected: Maximum 10 stores per page Pass: Response contains up to 10 stores

Store status

Test: GET /merchants/{merchantId}/status with OPEN store Expected: state: OK or WARNING with available: true Pass: is-connected validation returns OKTest: GET /merchants/{merchantId}/status with CLOSED store Expected: state: CLOSED with available: false Pass: opening-hours validation returns CLOSED

Pauses (Interruptions)

Test: Create valid pause with POST /interruptions Expected: Response 201 with ID of created pause Pass: Pause appears in GET /interruptionsTest: Create overlapping pause Expected: 409 InterruptionOverlap Pass: Error returnedTest: Remove pause with DELETE /interruptions/{id} Expected: Response 204 (no content) Pass: Pause no longer appears in listing

Hours

Test: Query hours with GET /opening-hours Expected: Array of configured shifts Pass: Each shift has dayOfWeek, start, durationTest: Update hours with multiple shifts Expected: Response 201 with created shifts Pass: GET /opening-hours returns new valuesTest: Try overlapping shifts Expected: 400 BadRequest Pass: Error returned

Error handling

Verify error responses for:

Code	Scenario	Check
`400`	Invalid parameters	Body includes `code` and `message`
`401`	Invalid/expired token	Clear message about authentication
`403`	No access to store	Error indicates insufficient permission
`409`	Resource conflict	Specific code (ex: `InterruptionOverlap`)
`429`	Rate limit	`Retry-After` header present
`500`	Server error	Generic message, no details exposed

Final considerations

Implement retry with exponential backoff for 5xx errors
Respect 1000 requests per second limit
Use minimum 30-second polling for status
Validate tokens before using in production
Test in homologation environment before going live

Next steps

Workflow Guide — Understand the complete integration flow
Operations — Configure operations for your store
Best Practices — Implement best practices

Was this page helpful?

Rate your experience in the new Developer portal:

On this page