> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getjusto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Notificaciones de estado de pedido
> Webhook que Justo envía para notificar cambios en el estado de los pedidos
Este endpoint es un webhook que Justo llamará para informar a la aplicación contenedora sobre cambios en el estado de los pedidos. La aplicación contenedora debe implementar este endpoint para recibir estas notificaciones y determinar cómo mostrarlas al usuario (por ejemplo, una notificación push o una alerta en la aplicación).
## Cuerpo de la solicitud
Identificador del usuario en la aplicación contenedora (el mismo usado en el onboarding).
Estado actual del pedido. Valores posibles: `pending`, `delivering`, `done`, `cancelled`, `nearToFinish`.
Identificador único del pedido en Justo.
Identificador del sitio web o tienda donde se realizó el pedido.
Indica si el pedido requiere un código de verificación para la entrega (opcional).
## Estados del pedido
Los diferentes estados que Justo puede enviar y su significado:
### `pending`
**Pedido aceptado por la tienda**
El pedido ha sido aceptado por la tienda y está siendo preparado.
### `delivering`
**Tu pedido va en camino**
El pedido ha sido preparado y está en camino hacia el destino.
### `nearToFinish`
**Tu pedido está llegando a destino**
El conductor está a menos de 300 metros del punto de entrega. Esta notificación puede enviarse múltiples veces.
La notificación con el estado `nearToFinish` puede enviarse varias veces, ya que el conductor puede cumplir repetidamente con la condición de estar a menos de 300 metros del punto de entrega. Para evitar efectos no deseados o duplicaciones en el sistema, es necesario que la contraparte implemente esta notificación de manera idempotente, garantizando que las múltiples recepciones de este estado no afecten el flujo ni el estado del pedido.
### `done`
**Pedido entregado**
El pedido ha sido entregado exitosamente al usuario.
### `cancelled`
**Pedido cancelado**
El pedido ha sido cancelado. Puede ser cancelado por la tienda, el usuario, o por problemas en el proceso.
## Ejemplo de solicitud - Pedido aceptado
```json theme={null}
{
"externalUserId": "user_12345",
"status": "pending",
"orderId": "order_xyz789",
"websiteId": "website_abc123",
"requiresDeliveryVerificationCode": false
}
```
## Ejemplo de solicitud - Pedido en camino
```json theme={null}
{
"externalUserId": "user_12345",
"status": "delivering",
"orderId": "order_xyz789",
"websiteId": "website_abc123",
"requiresDeliveryVerificationCode": true
}
```
## Ejemplo de solicitud - Pedido llegando a destino
```json theme={null}
{
"externalUserId": "user_12345",
"status": "nearToFinish",
"orderId": "order_xyz789",
"websiteId": "website_abc123",
"requiresDeliveryVerificationCode": true
}
```
## Ejemplo de solicitud - Pedido entregado
```json theme={null}
{
"externalUserId": "user_12345",
"status": "done",
"orderId": "order_xyz789",
"websiteId": "website_abc123",
"requiresDeliveryVerificationCode": false
}
```
## Ejemplo de solicitud - Pedido cancelado
```json theme={null}
{
"externalUserId": "user_12345",
"status": "cancelled",
"orderId": "order_xyz789",
"websiteId": "website_abc123",
"requiresDeliveryVerificationCode": false
}
```
## Respuesta esperada
La aplicación contenedora debe responder con un código de estado HTTP 200 para indicar que la notificación fue recibida correctamente.
### Respuesta exitosa
```json theme={null}
{
"received": true,
"message": "Notificación procesada exitosamente"
}
```
## Códigos de estado
La notificación fue recibida y procesada correctamente.
Error de validación. Los datos enviados no son válidos.
No autorizado. El token de autenticación es inválido o ha expirado.
Error interno del servidor de la aplicación contenedora. Justo puede reintentar el envío de la notificación.
## Notas importantes
Este endpoint debe implementarse con un mecanismo de autorización seguro (token de acceso) que valide que la solicitud proviene de Justo. El mecanismo específico debe coordinarse entre ambos equipos técnicos.
Es crítico que este endpoint sea idempotente, especialmente para el estado `nearToFinish` que puede enviarse múltiples veces. La aplicación debe poder procesar la misma notificación varias veces sin efectos secundarios.
La aplicación contenedora debe determinar cómo mostrar estas notificaciones al usuario. Algunas opciones incluyen:
* Notificaciones push
* Alertas en la aplicación
* Actualización del estado del pedido en la UI
* Sonidos o vibraciones
Si la aplicación contenedora no responde con un código 200, Justo puede reintentar el envío de la notificación. Se recomienda implementar un mecanismo de procesamiento asíncrono para evitar timeouts.
## Flujo de notificaciones
El flujo típico de notificaciones para un pedido exitoso sería:
1. `pending` - Pedido aceptado
2. `delivering` - Pedido en camino
3. `nearToFinish` - Pedido llegando (puede repetirse)
4. `done` - Pedido entregado
En caso de cancelación, se enviará directamente:
1. `cancelled` - Pedido cancelado
## OpenAPI
````yaml post /notifications/notify
openapi: 3.0.0
info:
title: Embedded Ordering API
version: 1.0.0
description: >
**Propuesta de API que debe ser implementada por la aplicación contenedora**
Este documento describe una propuesta de los endpoints que las marcas
(aplicaciones contenedoras)
deben implementar para que Justo pueda operar e integrar el marketplace
dentro de sus aplicaciones.
Los endpoints, esquemas y especificaciones aquí descritos son una propuesta
y pueden adaptarse
a los requerimientos específicos de cada sistema, siempre y cuando se
mantenga la funcionalidad
necesaria para que Justo pueda realizar las operaciones requeridas.
servers:
- url: https://your-app-domain.com
description: >-
Servidor de la aplicación contenedora (debe ser configurado por cada
implementación)
security: []
tags:
- name: auth
description: Endpoints de autenticación y onboarding
- name: payments
description: Endpoints de pagos
- name: notifications
description: Webhooks de notificaciones
paths:
/notifications/notify:
post:
tags:
- notifications
summary: Notificaciones de estado de pedido
description: >
**Propuesta de webhook** que Justo enviará para notificar cambios en el
estado de los pedidos.
Este endpoint debe ser implementado por la aplicación contenedora para
recibir las notificaciones
que Justo enviará sobre los cambios de estado de los pedidos.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationRequest'
responses:
'200':
description: La notificación fue recibida y procesada correctamente
content:
application/json:
schema:
type: object
properties:
received:
type: boolean
example: true
message:
type: string
example: Notificación procesada exitosamente
'400':
description: Error de validación. Los datos enviados no son válidos
'401':
description: No autorizado. El token de autenticación es inválido o ha expirado
'500':
description: >-
Error interno del servidor de la aplicación contenedora. Justo puede
reintentar el envío de la notificación
security:
- bearerAuth: []
components:
schemas:
NotificationRequest:
type: object
description: >
**Propuesta de esquema de webhook.** Estructura propuesta que Justo
enviará a la aplicación
contenedora para notificar cambios en el estado de los pedidos.
required:
- externalUserId
- status
- orderId
- websiteId
properties:
externalUserId:
type: string
description: Identificador del usuario en la aplicación contenedora
example: user_12345
status:
type: string
enum:
- pending
- delivering
- done
- cancelled
- nearToFinish
description: Estado actual del pedido
example: pending
orderId:
type: string
description: Identificador único del pedido en Justo
example: order_xyz789
websiteId:
type: string
description: Identificador del sitio web o tienda donde se realizó el pedido
example: website_abc123
requiresDeliveryVerificationCode:
type: boolean
description: >-
Indica si el pedido requiere un código de verificación para la
entrega
example: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
**Propuesta de esquema de autenticación.** Token de autenticación que
debe ser coordinado entre
Justo y la aplicación contenedora. El mecanismo específico debe
acordarse entre ambos equipos técnicos.
````