Catcher API documentation

• The Catcher API is a RESTful web service for developers to programmatically interact with Catcher Marketplace data and real-time delivery management functionality.
• Every bit of data exchanged between clients and the API is JSON over HTTPS.
• The base URL for the Catcher API is https://api.catcher.es , all the requests on this url use POST, PUT , GET methods and we need to add the specific end points mentioned below to this URL. Example, if you want to create a delivery order, you will Post to the below API: https://api.catcher.es/pitcher/v1/order
• API key is mandatory in all the API's request.
• All parameters marked with * are mandatory otherwise optional.
• If you have questions about using the API, want to share some feedback, or have come across a bug you'd like to report, write us an email at it@catcher.es

Authentication

Our authorization API must be called with the credentials provided by CATCHER to obtain the JWT that will allow them to invoke the API creation of orders.

IMPORTANT: the authorization JWT token is valid for 24 hours, the same should be stored within the consuming application and only request a new token after it has expired.

• ** POST - https://api.catcher.es/auth/v1/authorize

{

        "appId": "AD2DF34FGC",

        "appSecret" : "6lqjGTTTff566Nc10fFB",

        "grant_type": "client_secret"

}

{

    "data": {

        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6Im9yZGVyIiwidXNlcklkIjo5LCJsb2NhdGlvbklkIjoiOWY2MTQwOGUzYWZiNjMzZTUwY2RmMWIyMGRlNmY1NjYiLCJpYXQiOjE2NjkzMTc2MjQsImV4cCI6MTY2OTQwNDAyNH0.2D9SYK3JacIKYO9AYIYa8266nVkTMf23mYv3NOmyN9w"

    }

}

Order Create

• POST - https://api.catcher.es/pitcher/v1/order
• Header: Authorization: Bearer $token

{

    "locationId":"9f61408e3afb453e50cdf1b20de6f534",

    "orderPickupLocName": "Food palace",

    "orderPickupTime": "2022-11-24 20:35:00",

    "orderPaymentMethod": "card",

    "orderDeliveryLocation": "Calle de Núñez de Balboa, 112, 28006 Madrid",

    "addressDetails": "Piso A",

    "orderDeliveryLat": "39.479730",

    "orderDeliveryLong": "-0.381910",

    "orderPickupLocation": "Calle de Lleida, 17",

    "orderPickupLat": "39.483619",

    "orderPickupLong": "-0.376711",

    "userPhone": "+34634745678",

    "userName":"David Gonzales", 

    "orderSource": "Glovo", 

    "orderTotalAmount": "1045",

    "orderInstructions":"No incluir cubiertos.", 

    "orderCode":"GIVXG1N7",

    "externalId": "ZKERF-2JUO-TYUN"

}

IMPORTANT: Save the orderId , you will need it for another requests like order cancelation , order information or get driver location.

• orderPickupLocName (*): Name of the collection point.
• locationId (*) : LocationId assigned to your business. Must be provided by CATCHER
• orderPickupTime (*) : Pickup time of the Order. Format: "2022-09-12 09:29:02"
• orderDeliveryLocation (*): Delivery address
• addressDetail: Extra information about the shipping address.
• orderDeliveryLat (*): Delivery latitude
• orderDeliveryLong (*): Delivery Longitud
• orderPickupLocation (*): Pickup address
• orderPickupLat (*): Pickup Latitud
• orderPickupLong (*): Pickup Longitud
• orderSource (*): Origin of the order, example: Glovo, UberEats, JustEat OwnBusiness
• orderCode: Order code. The driver will need it to pickup the order
• orderPaymentMethod: Payment method. (cash,card)
• userPhone: Customer phone
• userName: Full name of the client
• orderTotalAmout: Total amount of the order. Where the 2 digits on the right represent the decimals. Example: For an order with a cost of 150.80 EUR, 15080 must be sent.
• orderInstructions: Extra data of the order
• externalId: Your internal order ID . We will send it in Orders Status Update webhook.

{

    "data": {

        "response": {

            "orderId": "3c86336e91090311bb027d526addf9ff",

            "externalId": "ZKERF-2JUO-TYUN"

        }

    },

    "status": true,

    "errors": null

}

Cancel Order

• PUT - https://api.catcher.es/pitcher/v1/order/cancel/$orderId
• Header: Authorization: Bearer $token

Get Order Status

• GET - https://api.catcher.es/pitcher/v1/order/status/$orderId
• Header: Authorization: Bearer $token

{

    "data": {

        "order": {

            "internalOrderId": "3c86336e910bd311bb027d526addf9ff",

            "status": "picking"

        }

    },

    "status": true,

    "errors": null

}

Status list

stacking: Waiting order to be stacked if configurated as well in your business console

matching: Waiting for Driver aceptation

matched: Accepted by a Driver

picking: Driver is going to pickup point

in_pickup_location: Driver is at pickup point waiting for the order

in_delivery: Driver is going to delivery location

finish: Order finished successfully

canceled: Order has been canceled

Get Order Detail

• GET - https://api.catcher.es/pitcher/v1/order/$orderId
• Header: Authorization: Bearer $token
• **
• IMPORTANT*: This endpoint will show you only same day orders. If you want to obtain details about orders from previous days you must point to this address

- GET - https://api.catcher.es/pitcher/v1/history/order/$orderId

**

{

    "data": {

        "order": {

            "detail": {

                "internalOrderId": "3c86336e910bd311bb027d526addf9ff",

                "code": "U609",

                "status": "finish",

                "receptionTime": "2023-01-23 12:52:17",

                "pickTime": "2023-01-23 13:01:54",

                "order_source": "LastApp",

                "aceptedByPitcher": "",

                "orderDescription": "",

                "pitcherInstructions": "",

                "visible": "yes",

                "pendingConfirmation": "",

                "pickingConfirmationCode": "",

                "deliveryConformationCode": "",

                "city": "Valencia",

                "pickupLocName": "Milanesas El Dorado"

            },

            "client": {

                "phone": "+34910780921",

                "phonePin": "",

                "name": "Erika"

            },

            "pickupAddress": {

                "lat": "39.4704167",

                "long": "-0.3477917",

                "location": "Poeta Mas i Ros 27",

                "locationName": "Burger palace"

            },

            "pitcher": {

                "name": "Burger palace",

                "cif": "46071741G",

                "socialName": "Burger palace SL",

                "location": "Poeta Mas i Ros 37",

                "phone": "692962334",

                "adminPhone": "692112864",

                "email": "direccion@burgerpalace.com",

                "city": "Valencia",

                "lat": "39.4704167",

                "long": "-0.3477917",

                "logo": "https://catcher-public-files.s3.eu-west-3.amazonaws.com/PITCHER_142/6357c916b18891025202213313423729001e40a81db55d9e12d44475479-600x600.jpg"

            },

            "catcher": {

                "firstName": "Herman",

                "lastName": "Salazar",

                "phone": "624351342",

                "img": "https://catcher-public-files.s3.eu-west-3.amazonaws.com/picture_noface.jpg",

                "lat": "39.4958351",

                "long": "-0.3475854",

                "acceptationTime": "",

                "pickupTime": "2023-01-23 13:15:54",

                "vehicle": "moto",

                "presetDeliveryTime": "2023-01-23 13:30:54",

                "deliveryTime": "2023-01-23 13:15:59",

                "inLocationTime": "2023-01-23 13:15:52",

                "city": "Valencia",

                "private": "yes"

            },

            "deliveryAddress": {

                "distance": "7.2",

                "location": "C/ del Santíssim Crist de la Fe i de la Providència, 46132 Almàssera, Valencia, Spain - Número 90, 1-1",

                "postal_code": "46132",

                "lat": "39.5100874",

                "long": "-0.3554133"

            },

            "payment": {

                "totalAmount": "28.1",

                "subtotalAmount": "",

                "presetPrice": "8.64",

                "matchedPrice": "0",

                "paymentMethod": "uber",

                "pitcherDeliveryPrice": ""

            }

        }

    },

    "status": true,

    "errors": null

}

Get Driver location

• GET - https://api.catcher.es/pitcher/v1/order/riderlocation/$orderId
• Header: Authorization: Bearer $token

{

    "data": {

        "last_lat": "39.4703259",

        "last_long": "-0.3478849"

    },

    "status": true,

    "errors": null

}

Webhook - Endpoint

You have to provide us an Endpoint to send you orders status changes , pricing and driver information

{

    "orderId": "3c86336e910bd311bb027d526addf9ff",

    "Order_status": "stacking;matching;matched;picking;in_pickup_location;in_delivery;finish;canceled",

    "hasCourier": true,

    "externalId": "",

    "courier": {

        "name": "Luis Driver",

        "phone": "34656626634",

        "longitude": "-3.693725",

        "latitude": "40.4676228",

        "transportType": "moto",

      "transportPrice": "3.90"

    }

}

Order_status: matched, picking, in_pickup _location, in_delivery, finish, canceled

transportType: bicycle, moto, car, scooter

POSTMAN COLLECTION LINK

https://catcher.es/postman/CATCHER-API.json

Need More Help?

You can talk to us directly through it@catcher.es